Skip to content

Changelog

All notable changes to the Silo SDK will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

[0.16.1] - 2026-10-19

Added

  • python -m silo_sdk_mcp --describe TOOL shows a tool's arguments before you call it. It prints the tool's description and, for each argument, its type, whether it is required, its default, its limits and its format with an example. It reads the same input schema MCP clients receive, makes no API call and needs no credentials. It exits 0, or 2 for an unknown tool, and cannot be combined with --call, --list-tools or the server options. The error for an unknown argument name now points at it.

Changed

  • The docs and dev extras cap pymdown-extensions below 12. Version 12 changed an interface that mkdocstrings uses, and building the API reference pages failed.
  • Every MCP tool argument is described in the published schema. Each argument in a tool's inputSchema now has a description stating what it is, its format with an example, units, whether it is required and its default, limits, and which arguments exclude each other. Limits the SDK already enforced are also stated as schema constraints, for example limit 1 to 1000 and start_seq at least 0 on a8_extract_logs. Accepted input is unchanged, with the one exception below.
  • a8_update_context refuses a max_uses below 1. It used to pass any integer to the platform, which stores 0 or a negative value and then refuses every launch of the context with "context has reached maximum uses". The call now fails at once, naming the argument, as a8_create_context already did. To switch a context off, pass enabled: false.
  • Tool descriptions cover the rules that used to fail calls. a8_get_session_report states that it takes at most one identifier, that its dates are MM-DD-YYYY, and that it returns aggregates only. a8_extract_logs states that start_seq is required, that start_date / end_date count days before today, how to page with is_more / next_seq, which log type answers which question (SESSION for egress and execution server; LOCATION_CHANGE is page navigation), and which types carry browsing history. Return-value documentation was corrected where it named fields the platform does not send, including a8_get_session_report, a8_upload_file, a8_modify_file, a8_list_files, a8_get_user, a8_modify_user and a8_update_org.
  • Argument errors say what a valid call looks like. A missing, mistyped or out-of-range argument used to fail with the validation library's bare message, such as "Field required". The error now names each bad argument, the value given, the expected type and limits, and the argument's description, and ends with the --describe command for the tool. A missing start_seq on a8_extract_logs points at a8_get_extract_logs_info. MCP clients and --call receive the same text.
  • A days-ago value too large to be a day count gets a clear error. Passing an epoch timestamp as start_date or end_date to extract_logs() used to raise "days=...; must have magnitude <= 999999999". It now raises ValidationError explaining that the value is a number of days before today, not a date or timestamp.

Security

  • The mcp-server extra requires mcp 1.30.0 or later. Versions 1.28.1 to 1.29.x, which the previous minimum allowed, are affected by a known vulnerability that 1.30.0 fixes. An existing install that already resolved to 1.30.0 or later is unaffected; pip install -U "silo-sdk[mcp-server]" upgrades one that did not.

Fixed

The fixes below were found by checking documented SDK behaviour against the platform, and confirmed by live API testing where marked. None changes the result of a call that worked before, except where an entry says so.

Browsing contexts

  • update_context() documentation said omitted fields were left unchanged. They are removed. Confirmed by live API testing: the platform replaces the stored context_data with the one you send, then re-applies the creation defaults. An update that sent only urls removed the context's restrict_ips (its IP lock) and its egress, and turned a toolbox-standalone context into silo-ruby. The SDK, a8_update_context and their examples now say to send the complete context_data. update_context() logs a warning when context_data has no session_type, and when the platform reports that no context was updated. That happens for an unknown or deleted ID, which is not reported as an error. Return values are unchanged.
  • expires given as epoch seconds in a string failed. The platform reads a string as an ISO 8601 date, so "1767225600" was rejected (confirmed by live API testing). The MCP tools documented that form and refused a plain number. The SDK and MCP tools, including a8_create_browsing_url, now accept a number, and convert an all-digit string to a number before sending. "+SECONDS" and ISO 8601 strings are sent unchanged.
  • Egress categories on a context may use lists and null in the SDK, a8_create_context, a8_update_context and a8_create_browsing_url: availability and connectivity accept a single value, a list or null, and egress_info.categories may be null, as the platform allows. protocol stays single-valued. Harvest tasks are unchanged.
  • Documentation corrections: list_egresses() returns every level of the egress hierarchy (World, regions, countries, cities), not only cities. The default response for the /ctx/ endpoint is url. An update stores an egress or policy without the checks applied at creation.

File storage

  • A download blocked by malware scanning was saved as the file. The platform answers a blocked download with HTTP 200 and a JSON error body. The SDK wrote that body to the output path and reported success, and a8_read_file_content returned it as the file's text. All download paths now raise FileAPIError with the platform's error and malware details, and leave no file behind.
  • A download shorter than its Content-Length was retried, then lost. For some files the platform's Content-Length exceeds the body by 28 bytes. The retrying download treated this as a network fault, downloaded the file three more times, then deleted the partial result. A short body is no longer retried. It raises FileAPIError with the expected and received byte counts, and truncated data is never kept.
  • Upload and download errors include the platform's reason. An HTTP 400 from an upload or download now carries the reason the platform gave, such as "file is folder", "file already exists" or a disallowed character. upload_file() refuses a name containing ^ % \ /, or a path containing ^ % \, before sending, since the platform always rejects them.
  • modify_file() with a numeric expire_ts failed on the platform. Numbers are now sent as strings. All five accepted forms are documented: epoch seconds, now+SECONDS, +SECONDS to extend the current expiry, reset for the bucket default, and an ISO 8601 date.
  • get_file_info() and modify_file() reported a platform error as "Unexpected response format", with the full response in the message. They now raise FileAPIError with the platform's message, and redact any response included in an error. get_file_info() with no bucket configured fails before sending a request.
  • find_files() documentation promised matching the platform does not do. Confirmed by live API testing: name is matched exactly (ignoring case), with no wildcards, so "*.pdf" matches nothing. path matches files directly in that folder only. file_type filters by file or directory, not by MIME type or extension. metadata_filters have no effect, and the SDK now warns when they are passed. The "server-side cap" warning was removed, because the platform returns every match.
  • Failed downloads caused by a malware scan error are no longer retried, since each retry repeats the scan.

Web harvesting

  • Omitted egress categories are no longer sent as null. When protocol was not given, the SDK sent "protocol": null on harvest tasks. The platform still uses direct egress in that case, so routing was not affected, but the request now leaves out any category the caller did not set.
  • Valid task options were refused. Visual tasks accept a top-level cookies string. notes is accepted on asset, single and video tasks. run_after accepts float epochs and any ISO 8601 date with a timezone (offsets, fractional seconds), and refuses True, which was read as 1970 and ran the task at once, and a value with surrounding whitespace.
  • Options set to False were sent and read as enabled. The platform treats an option's presence as on, so all_files=False turned directory output on. Top-level options set to False or None are no longer sent.
  • egress_info.server_set on a harvest task is removed before sending. The SDK warned that it would be ignored, then sent it, and the platform rejected the task.
  • recursive on a single task is refused with a clear error, by TaskBuilder and by create_harvest_task() alike, since the platform always rejects recursion for single tasks. level alone is still accepted.
  • A task option given the wrong kind of value is refused before the task is created. Each harvest option is either a flag, enabled by passing True, or an option that needs a value. The SDK used to send wait_nav: True as a bare flag, and a value for a flag option, and the task then failed when it ran ("option … requires an argument"). Both mistakes now raise ValidationError naming the option.
  • Documentation corrections: wait_nav and xff take a value. Video cookies takes the cookie file's content, not a path. all_files=True returns a directory that download_task_result() cannot fetch. Deleting a running task stops it at the platform's next check rather than at once.
  • find_harvest_task(..., finished=...) no longer returns a cached record that ignores finished. The async result download no longer blocks the event loop when creating its output directory.

Users and organizations

  • Security: promote_user_to_admin() could grant admin rights in the wrong organization. Given an organization name that matches more than one organization, the platform grants admin in the first match. The SDK now resolves the name first, and refuses to promote if it is ambiguous or not found.
  • add_user() required given_name and surname; the platform does not. Both are now optional in add_user(), a8_add_user and a8_bulk_add_users. email stays required, as the platform requires it.
  • list_users() documentation said lockout fields were missing. Confirmed by live API testing: each user record from list_users() has the same fields as get_user(), including is_locked, failed_login_attempts, oob_locked and oob_lock_expires_at.
  • modify_user() replaces all custom fields. Custom fields left out of custom_fields are deleted. The documentation said they were kept. To change one field, read the user, merge, and send the full set.
  • delete_user() and the batch-delete note: the platform returns "user not found" only when nothing was deleted. The documentation and the note in batch results no longer describe it as a false error.
  • get_proxy_policy() no longer sends a parameter the platform ignores.
  • Documentation corrections:
  • get_sso_policy() needs an organization.
  • Partner SSO creation needs a parent organization.
  • The partner SSO error messages are listed as the platform sends them.
  • Proxy policy: adding a name that already exists adds a duplicate. Reading a policy returns only that organization's own proxies. Deleting fails when the organization has no policy of its own.
  • Organization names are matched exactly, never partially.
  • get_org()'s current_users counts the whole sub-tree.
  • Session report: end_date is exclusive, and org_id covers that organization only, while org_name includes its children.
  • Unsuspending an active user returns a server error.
  • bypass_code is always returned.

Log extraction

  • Documentation said leaving out include_suborgs returns only the named organization. It includes sub-organizations. Confirmed by live API testing. Pass include_suborgs=False for the named organization only.
  • start_date currently has no effect when start_seq is sent, and start_seq is always sent. Confirmed by live API testing; the documentation now says so. Use end_date, or filter the results, to narrow by date.
  • CSV exports dropped fields. The ADMIN_AUDIT, NEXUS, LAUNCHER and ENC field lists were missing fields the platform sends, such as action and label on ADMIN_AUDIT and text and filename on NEXUS. Single-type exports and a8_export_logs_csv now also keep any field not yet in the schema, so an export can gain columns. New columns are added after the existing ones. a8_export_logs_csv gathers rows in a temporary file rather than in memory before writing.
  • a8_export_logs_csv now guards against CSV formula injection, as the SDK's own export does. A log value starting with a formula character, such as a URL beginning with =, is written so that a spreadsheet shows it as text instead of running it.
  • Documentation corrections:
  • min_seq is the earliest AUTH record, not the earliest record of every type.
  • A query that times out after 120 seconds may still hold the extraction lock, so wait before retrying.
  • get_log_types()'s version is a string.
  • end_date is ignored when end_seq is given.

Postman collection

  • The List Users and Get User examples show the lockout fields, and one-time credentials are masked in saved examples. The example generator now masks temporary_password and bypass_code, and a test checks the collection for unmasked credentials.
  • Three requests sent values the platform misreads.
  • Create Context — Custom Policy sent "expires": "3600", meant as one hour, which the platform reads as an ISO 8601 date. It now sends "+3600".
  • Find Files — Date Range sent file_type, created_after, created_before and limit, which the platform ignores, so it returned every file and then pointed later file requests at whichever one came first. It now sends type, :created_after and :created_before, and leaves file_id alone.
  • Extract Logs — Date Range sent start_seq with start_time, so the time window was ignored. It now sends the time window alone.

Scripts

  • scheduled_visual_harvest.py --xff takes a value. It was an on/off switch, but the platform requires a value for this option, so a capture with --xff always failed.
  • batch_user_provisioning.py no longer requires given_name and surname. Only username and email are required, as on the platform.
  • extract_all_logs.py --days and export_logs.py --days-back say in their help that the date window currently has no effect, for the reason given under Log extraction.

[0.16.0] - 2026-10-06

Added

  • scripts/reports.py brings the session and usage reports together. One CLI with three subcommands: session, org-usage and user-usage. Each takes the same flags as the script it replaces and keeps its output, error messages and exit codes.
  • scripts/contexts.py creates and manages browsing contexts. create and bulk take over from the two context-creation scripts with the same flags. New subcommands: get prints a context's details as JSON, update changes its maximum uses or expiration, and delete removes it. update and delete refuse to run without --yes (exit status 2). With --yes they first print the target API URL and its environment (eng, qa or production) to stderr.
  • scripts/file_manager.py can upload, modify and delete files. upload --file LOCAL [--dest-path DIR] [--name NAME] adds a file and runs without confirmation. modify changes a file's name, folder, content type or expiry (--expire-ts now+SECONDS). delete removes a file permanently. modify and delete require --yes and exit 2 without it. All three print the target API URL and its environment to stderr before writing, so stdout carries only the result.
  • scripts/dev/cleanup.py has --help and --dry-run. --dry-run lists what would be removed and removes nothing.
  • MCP tools declare whether they read, write or destroy. Every tool carries MCP annotations (readOnlyHint, destructiveHint, openWorldHint) so a client can tell reads from writes and ask before changing anything, and --list-tools shows each tool's kind. The three tools that only write a local file are marked read-only because they change no Silo state.
  • python -m silo_sdk_mcp --call TOOL runs any MCP tool from a shell. It calls the tool in-process with the same code the server uses, so it works where no MCP client can load the server. Arguments come from --args or --args-file; any tool that is not read-only is refused without --yes; credentials in the output are redacted unless --reveal is given, and tools that return a new credential (a8_reset_pin, a8_add_user, a8_bulk_add_users, and a8_batch_request containing reset_pin or adduser) are refused without it; unknown argument names are rejected (exit 2). Exit codes are 0 success, 1 tool error, 2 usage or configuration error. silo_sdk.utils.config.environment_for_url() classifies an API URL as eng, qa or production.
  • How-to guide for running MCP tools from a shell. A new how-to guide, Run MCP tools from a shell, walks through python -m silo_sdk_mcp --call: finding tools and arguments, read and write examples, --yes and --reveal, output and exit codes, troubleshooting, and when a script in scripts/ is the better fit.
  • The MCP server can serve HTTPS, and can require client certificates. --ssl-certfile and --ssl-keyfile (or MCP_TLS_CERTFILE and MCP_TLS_KEYFILE) turn on TLS for the streamable-http and sse transports. --ssl-client-ca (MCP_TLS_CLIENT_CA) additionally requires every client to present a certificate signed by that CA (mutual TLS), checked before the Bearer token. The server checks the files at startup and refuses to start, with a one-line error, when only one of certificate and key is set, a client CA is set without a certificate and key, a path is missing or is a directory, a file is unreadable, the key does not match the certificate, the key is passphrase-protected (not supported), or the client CA is not a PEM file. Connections use TLS 1.2 or later, and TLS 1.2 is limited to forward-secret AEAD cipher suites. The options apply to the HTTP transports only: --transport stdio refuses the flags and ignores the variables. docker-compose.mcp-tls.yml, configured with MCP_TLS_DIR, turns it on for the Compose deployment. Without these settings the server serves plain HTTP as before. Docker image builds now exclude key and certificate files (*.key, *.pem, *.crt, *.p12, *.pfx, certs/) anywhere in the build context, so a custom image that copies its own CA bundle or certificates from the repository must add them another way.

  • create_context() can validate egress against the platform's live directory. With validate_egress=True, or the new LIVE_EGRESS_VALIDATION setting, it asks list_egresses() what the user may actually select and raises EgressNotOfferedError, a new ValidationError subclass, before creating a context the platform would refuse, naming what is offered. Catch the subclass to tell this refusal, which validate_egress=False overrides, from a malformed request. World, regions and countries are accepted when something beneath them is offered, and categories are checked as a combination. It skips the check, with a warning, for an egress_info that names a server_set and for a context created for an org rather than a user. It never blocks when it cannot answer: with no username, an empty directory (the platform chooses the egress; for a standard session it warns that Traffic Manager rules, if the org has them, will refuse a pinned egress), or a failed lookup, it logs and falls back to the built-in checks. Off by default; create_research_session() forwards the argument.

  • Harvest egress lookups by task type. HarvesterAPI.list_harvest_egresses(task_type) reports the egress a harvest task can draw from: the asset pool for asset and wget, the browsing pool for visual, video and single, for the new HARVEST_EGRESS_ORG setting (A8_HARVEST_EGRESS_ORG), or TOP_ORG when it is unset. Harvest resolves egress for the organization the harvest token belongs to, and a lookup sees only egress provisioned to that organization and those above it, so set HARVEST_EGRESS_ORG when the harvest token belongs to a sub-org of TOP_ORG; otherwise the lookup finds nothing and the check is skipped. With LIVE_EGRESS_VALIDATION or validate_egress=True, create_harvest_task() and create_harvest_task_async() check the egress against it and warn when it is not listed. They never block, because an organization's Launcher Options hide regions from the list but not from harvest. check_harvest_egress() runs the check on its own and returns the reason; pass warn=False to get the reason without the warning, when you act on it yourself. Each pool's listing is reused for a minute, a failed lookup included, so a bulk run asks once and logs a failure once, and concurrent tasks share one lookup.

  • list_egresses() takes service_type ("egress" or "harvest-asset") to report a specific server pool. An unknown value raises ValidationError instead of returning the empty list the platform sends.
  • bulk_create_contexts() takes validate_egress and checks the shared egress once for the batch, before creating any context.
  • The examples and scripts can list live egress. --list-egress --live in browsing_demo.py, news_spider_harvest.py and scripts/scheduled_visual_harvest.py; --validate-egress in scripts/contexts.py create and bulk.
  • The Postman collection documents service_type on List Egresses and adds List Harvest Egresses requests for each pool.

Changed

  • Maintainer tools moved to scripts/dev/. cleanup.py, validate_log_schemas.py and run_postman_eval.sh are for working on the SDK rather than on a Silo deployment. They now find the repository root wherever they are run from. run_postman_eval.sh --help prints usage without reading .env.
  • The scripts name their target environment the same way the SDK and the MCP tool runner do, using silo_sdk.utils.config.environment_for_url.
  • The scripts guide is reorganized. It has an overview table of the operational CLIs and their subcommands, a separate section for maintainer tools, a "Renamed scripts" table, and a pointer to python -m silo_sdk_mcp --call for operations no script covers. The user-usage examples now use the flags the script accepts (--no-suspended, --sort time).
  • bulk_create_contexts() logs an egress warning once per batch. An unknown egress_region or an unavailable category used to be reported again for every context in the batch; it is now reported once.

  • --live on its own is now a usage error in scripts/scheduled_visual_harvest.py and the browsing and news spider examples. It only modifies --list-egress, and was silently ignored without it.

  • create_context() and bulk_create_contexts() reject an invalid session_type locally. A value other than "silo-ruby" or "toolbox-standalone", including an empty string, now raises ValidationError instead of being sent to the platform. The MCP tools treat a blank session_type as unset. bulk_create_contexts() now raises ValidationError up front for an invalid egress_region, categories or session_type, as create_context() already did. Previously it logged each per-URL failure and returned no contexts.

  • The MCP harvest tools check the egress against the task type's pool. With MCP_EGRESS_VALIDATION=live (the default), a8_create_harvest_task and a8_harvest_url refuse an egress the pool's directory does not list, naming what it offers; pass allow_unlisted_egress=true to send it anyway. a8_list_egresses takes service_type.

  • scripts/scheduled_visual_harvest.py and the news spider example warn on an unknown --egress instead of exiting. They checked it against the SDK's compiled-in list, which lags the platform, so a newly provisioned location could not be used. The platform still rejects a location it does not offer.

  • The MCP server validates egress against the live directory by default. a8_create_context, a8_create_research_session and a8_create_browsing_url now check a requested egress against the user's directory before creating a context, and reject one the platform does not offer, naming what is. Because an org's Launcher Options can hide a region from that directory, each of the three takes allow_unlisted_egress=true to create the context anyway. Set MCP_EGRESS_VALIDATION=offline to keep only the built-in checks. a8_list_egress_locations now says it returns the SDK's compiled-in list and points to a8_list_egresses for the live answer.

  • The MCP server caps how long a8_wait_for_harvest_task and a8_harvest_url will wait. A wait above MCP_MAX_WAIT_SECONDS (default 1800, which is a8_harvest_url's default wait) is now rejected with an error naming the cap, as is a polling interval longer than the wait. a8_harvest_url checks before it creates the harvest task, so a rejected call leaves nothing running. Calls that use the default waits are unaffected. A wait that times out does not cancel the task, so call a8_wait_for_harvest_task again to keep waiting. The long-wait thread pool bounds how many waits run at once; this cap bounds how long each one can hold a worker. Anything but a positive integer in MCP_MAX_WAIT_SECONDS stops the server at startup.

Deprecated

  • The old script names still work, but are scheduled for removal in a future release. session_report.py, org_usage_report.py, user_usage_report.py, create_context.py, bulk_create_contexts.py, cleanup.py, validate_log_schemas.py and run_postman_eval.sh each print a deprecation notice to stderr, then run their replacement with the same arguments. The scripts guide's "Renamed scripts" table maps each one to its replacement.

Fixed

  • HarvesterAPI now closes the file client it uses for downloads. HarvesterAPI creates its own FileAPI to fetch task results, and neither close(), cleanup_resources() nor leaving a with HarvesterAPI(...) block closed it, so that client's HTTP connections stayed open until the object was garbage-collected. All three now close it along with the harvester's own session.

  • Asset and wget harvest tasks default to an egress the platform resolves. The SDK named the asset pool's New York location "New York City", which the platform does not recognise: an asset task sent with it was accepted and then failed with No egress location found. The location is "New York, NY", the same name browsing uses. default_egress_for_task_type("asset"), VALID_ASSET_EGRESS_LOCATIONS and the examples now use it; "New York City" on an asset task now logs a warning.

  • Harvest egress validation reports a malformed categories as ValidationError instead of crashing with AttributeError, no longer warns about "World" on an asset task, warns that another region or country works on an asset task only if an asset location sits beneath it, and warns that a server_set is ignored by harvest tasks.

  • examples/browsing_demo.py runs again. It failed at import on a name that had been removed from the SDK.

  • check_egress_against_directory() accepts World, regions and countries, and checks categories together. It matched exact location names only, so a name from higher in the hierarchy was refused though the platform takes it, and it passed a connectivity and protocol that were each offered but never in the same combination.

  • The five "(As Available)" egress locations now carry connectivity and protocol data. The suffix is part of each location's real name, so "Mali (As Available)", "Morocco (As Available)", "Nigeria (As Available)", "Israel (As Available)" and "Tbilisi (As Available)" remain the names to use. Their categories were previously unrecorded and passed through unchecked; they are now validated like every other location and listed by get_egress_locations(include_details=True). The bare names "Mali", "Morocco", "Nigeria" and "Israel" are no longer listed as countries, because no country level sits above those locations; passing one now logs a warning rather than being accepted silently. "Georgia" still covers Tbilisi.

  • An unrecognised egress connectivity no longer refuses the request. categories["connectivity"] was checked against the SDK's own list of four values and raised ValidationError for anything else, though the platform treats connectivity as free-form and reports values that list does not have, such as wireless. It now logs a warning and sends the request, as an unknown location name already does since 0.15.0. A connectivity that is not a string still raises, and availability and protocol are still checked strictly.

  • Harvest waits no longer overshoot max_wait_time. wait_for_completion, wait_for_completion_with_progress and wait_for_completion_async slept the full check_interval between status checks however little time was left, so a wait could run up to one interval past its limit, and an interval far longer than the limit held the caller for that whole interval. They now sleep no further than the limit, check the status once more there, and then time out, so a task that finishes by the deadline is still returned.

  • wait_for_completion_async checks the status at least once. With a check_interval longer than max_wait_time it made no status request at all and reported a timeout.

  • HarvesterAPI names the variable to set when a token is missing, as the other clients do. 0.15.0 added the (set A8_<KEY>) hint to the missing-token error, but HarvesterAPI checks its configuration with its own validator first, so it still raised Missing required token: SCRAPE_TOKEN without it. It now reads Missing required token: SCRAPE_TOKEN (set A8_SCRAPE_TOKEN), and likewise for BUCKET_ID.

Security

  • Long harvest waits in the MCP server can no longer starve every other tool. a8_wait_for_harvest_task and a8_harvest_url block for as long as the caller asks (timeout_seconds, and max_wait_seconds with a default of 1800), and they shared one thread pool with every other tool. A worker cannot be reclaimed once a wait has started, since a client cancelling the call frees its own request but not the thread. About three dozen concurrent waits therefore filled the pool, and every later call, including quick user and org lookups, queued behind them while the server still looked healthy. Harvested web content that talks a model into starting many long waits is the realistic way to reach that state. The two tools now run on a pool of their own, so they can only fill that pool, and the other tools keep a pool the same size as before. Neither tool's parameters or results change.
  • New MCP_LONG_WAIT_WORKERS environment variable sets how many long waits can run at once. The default is 8. Further waits queue until one finishes, and a wait cancelled while still queued never starts. If your workflow runs more simultaneous harvest waits than that, raise it. Anything but a positive integer stops the server at startup.

  • The urllib3 minimum is raised to 2.8.0. The previous floor, 2.7.0, has three known vulnerabilities (PYSEC-2026-4175, PYSEC-2026-4176 and PYSEC-2026-4177), all fixed in 2.8.0. A default install already resolved to a current release, so this matters only where another package pins urllib3 to an older version: the SDK's requirement now refuses 2.7.x rather than accepting it.

[0.15.0] - 2026-10-02

0.15.0 was re-cut before it was published. An earlier 0.15.0 tag was never pushed, reached no package index and had no GitHub release, so nothing was withdrawn and no version number was burned. Everything described below as fixed or changed is relative to 0.14.2, the last release anyone could install.

Added

  • LogExtractionAPI.extract_logs_per_type() — extract several log types without one bad type failing the lot. A combined extract_logs() call fails as a whole when any single type is unavailable, most often ENC on an org without encryption, even though every other type would have succeeded. The new method makes one request per type and merges the pages; a type that fails is reported in type_errors instead of failing the call, and only if every type fails is the first error re-raised. Previously this recovery existed only inside the MCP server's fallback_per_type option, so SDK callers had to rebuild it themselves — and the obvious way to merge the pages is wrong (see the next item).
  • The merged next_seq is the lowest resume point, not the highest. Each type paginates independently and stops at a different sequence number. Resuming from the highest skips every row a lagging type has not sent yet, with no error. The merged page resumes from the lowest next_seq among types still reporting is_more, so the next page may repeat rows of the types that were ahead — deduplicate by seq_id. With no type reporting more, next_seq is the lowest next_seq any type reported, so a poller keeps advancing; it is the start_seq you passed only when no type reported one.
  • Types in type_errors are not covered by next_seq. A failed type returned nothing, so resuming it from the merged next_seq would skip its rows. Re-request failed types from the original start_seq. is_more is not forced to True for them, because a type that fails permanently (ENC on an org without encryption) would then never let a poller finish.
  • merge_per_type_extracts(), exported from silo_sdk.logging, is the merge step on its own, for callers who make the per-type requests themselves (for example, to add their own retry). The MCP server's fallback_per_type now uses it, so the SDK and the MCP tool answer identically.

  • BrowsingAPI.list_egresses() — ask the platform which egress locations you can actually use. get_egress_locations() reads a table compiled into the SDK: it lists every location the platform has, which is not the same question as which ones a given org or user may select right now. The new method asks the server, which answers after applying entitlements, the org's Launcher Options policy, and an up/down check, and returns one entry per location with its name, its path through the location hierarchy (broadest to narrowest, so you can group by region without a static table), and the categories combinations it offers. Give exactly one of username, user_id, org_id or org_name; the SDK enforces that locally so a typo costs an error rather than a round trip. The static table is still the right tool offline, in tests, and for fast validation — this one is for when the answer matters.

  • An empty list is a real answer, not a failure. It means no egress can be pinned, most often because the org runs Traffic Manager rules that choose the egress themselves, but also when the org's policy has disabled every provisioned region or none is currently up. Treat it as "let the platform decide."
  • It behaves unlike every other call in the SDK, in two ways worth knowing. It is a plain REST endpoint rather than a command-array call, so failures arrive as real HTTP status codes instead of an error element inside an HTTP 200, and the token travels in an Authorization: Bearer header rather than in a setauth command. It needs an ADMIN_TOKEN; a sync token is refused with 403, as is an admin grant that does not cover users when you select by username or user_id.
  • check_egress_against_directory(egress_info, directory) validates an egress_info against a directory you fetched, and is the authoritative counterpart to the compiled-in checks described under Changed below. Pass it the list list_egresses() returned; it raises ValidationError if the location is not in it, or if a requested connectivity, availability or protocol is not among the combinations offered at that location for that caller, naming what is available in both cases. Unlike the static checks it raises rather than warns, because a directory fetched seconds ago is not a guess. An empty directory rejects everything with "no pinnable egress" — see above for why that is a real answer.
  • Two new response shapes, EgressDirectoryEntry and EgressCategoryOption, describe what comes back. Note that categories is a list of objects coming out of the directory, while the categories you send in on EgressInfo is a single dict of scalars — the two look similar and are not interchangeable.

  • UserManagementAPI.unlock_user() — clear a lockout without touching suspension. A locked account and a suspended one are different states with different causes: suspension is an administrative action, a lockout is the platform's response to failed authentication. There was previously no way to clear the latter from the SDK, so the only remedy for a user who had fatfingered their PIN too many times was the admin console. One call now clears both lock mechanisms — the failed-login lock (is_locked / failed_login_attempts), set by failed PIN or temporary-password attempts and permanent until cleared, and the out-of-band lock (oob_locked / oob_lock_expires_at), set by failed SMS or voice codes and otherwise self-clearing on expiry. An account can be under both at once, so clearing one is not reliably enough to restore access; that is why this clears both rather than offering the choice.

  • UserRecord documents the four lockout fields, which the platform has been returning on get_user all along. Checking only is_locked will report a user who cannot log in as unlocked.
  • You cannot unlock yourself — the platform rejects a request whose target is the account behind the auth token, as it already does for suspend_user and unsuspend_user. The SDK deliberately does not pre-empt this: it cannot tell which account a token represents, so any client-side check would be a guess, and the server's message is clear enough to act on. That restriction is now documented on all three methods.

  • LogExtractionAPI.get_log_types() — the supported log types, from the deployment you are actually talking to. get_valid_log_types() returns a list compiled into the SDK, which goes stale as the platform adds types, and there was no way to tell whether it had. Names come back in SDK form with underscores, so they can be passed straight to extract_logs() — the four types that use spaces on the wire (BLOCKED URL, CASE MANAGER, LOCATION CHANGE, POST DATA) are translated for you. The static list is unchanged and remains the offline answer.

  • Do not use the returned version as a cache key yet. The method accepts a version argument as a change check, so an unchanged list need not be re-sent, but two deployments exposing different type lists have been observed reporting the same version — a client that skips the fetch on an unchanged version can therefore miss a newly added type. Call it without version until that is fixed upstream.

  • create_context() accepts egress_info, the newer single-object form of egress selection. Previously the egress was chosen with two separate parameters, egress_region and categories. The object form takes the location as name, carries the same categories, and additionally allows server_set, which has no equivalent in the older parameters and is the only reason to reach for it if the older form already works for you. create_harvest_task() has always used this shape; this brings browsing contexts in line.

  • The two forms are mutually exclusive. The platform rejects a request that mixes egress_info with egress_region or categories, and so does the SDK, naming the conflicting parameters — the error arrives before the round trip and reaches callers who never see a response body.

  • sovereign is accepted as an egress protocol, alongside direct and tor, for routing through an in-country egress to satisfy data-residency requirements. Which locations provision it is not published, so it is deliberately absent from the SDK's per-location table and the location cross-check is skipped for it: a "not available there" from a table with no data for the protocol would be an invention rather than a finding, and the platform rejects an unprovisioned combination itself. The type check still applies, so a misspelling is still caught locally. is_protocol_supported() and is_combination_supported() document the exemption, and the latter degrades to a connectivity-only check when the protocol is sovereign.

  • Two new MCP tools, a8_list_egresses and a8_unlock_user, wrapping the SDK methods above. See below for the six more this release adds and for the resulting tool count.

  • ENABLE_REQUEST_LOGGING now does something. The key shipped in every bundled config file and was documented as inert — no SDK code read it. Setting it to true now logs one INFO line per outbound request with the HTTP method, the URL and the command array being sent, which is the "what did the SDK actually send" view you want when reconciling behavior against the API, without turning on every DEBUG line in the SDK to get it. Credentials are removed before anything is written: fields whose names contain token, auth, password, secret, credential or key are masked, as is the token carried by the setauth command, and the token value is then stripped from the rendered line by literal match as a second pass. Requests only — responses are not logged, because response bodies carry user records, file contents and log extracts, and that is a data-classification decision rather than a debugging one. Non-credential parameters (usernames, org names, paths, search patterns) are logged verbatim, so treat the log at the sensitivity of the data your calls touch. Default remains false. The key reads as a boolean whether it arrives as one or as a string: "1", "true", "yes" and "on" enable it, case-insensitively, and everything else — including "false" and "0" — leaves it off. A value supplied through ${VAR} substitution arrives as text, and a plain truth test on "false" is True, so a switch turned off in the environment would have come back on.

  • Three config keys are now settable from the environment: A8_ENABLE_REQUEST_LOGGING, A8_ENABLE_STATUS_CACHE and A8_STATUS_CACHE_TTL. All three were hardcoded literals in the shipped config files, so the only way to change one was to edit a version-controlled file — awkward for a diagnostic you want on for a single run, and impossible for a containerized deployment that mounts the config read-only. They now carry ${A8_*} templates with their previous values as the defaults, and the container passes the variables through. This holds on every transport, including the MCP server's streamable-HTTP mode: that mode builds its configuration from credentials.yaml alone and never opens the shipped config files, so the same three variables — plus A8_DEFAULT_MAX_USES, which was inert there for the same reason — are read as fallbacks for any key the credentials file leaves out. Spell a key out in credentials.yaml to pin it for that client instead. Two keys were deliberately left as literals: DEBUG_MODE and ENABLE_ENCRYPTION are accepted and stored but read by no code path, so an environment variable for either would be a switch wired to nothing. Alongside this, both config loaders — the SDK's and the MCP credentials-file one — now cast boolean keys the way they already cast numeric ones: substitution produces strings, and a plain truth test on "false" is True, so a switch turned off in the environment would have read as on. 1, true, yes and on mean on, case-insensitively; everything else means off, and an unrecognized value is off rather than an error — there is no such thing as an unparseable switch, only one that is not any of the spellings meaning on.

  • The test suite now checks documented return fields against real captured responses. Every Returns: section that lists fields as a bullet list is compared against the responses saved in the bundled Postman collection, and a field named in the docstring but absent from every capture fails the suite. This class of defect had shipped six times across four modules, and once survived being fixed — a field list rewritten from the API documentation was itself wrong. Reading documentation cannot catch it; only comparing against a real response can. The check states its own limits (prose sections are skipped, methods that deliberately rename wire fields are listed and excluded, and only commands with captures are covered) and carries floors on how much it is covering, so a future parsing regression fails loudly instead of passing vacuously.

  • log_types accepts a bare string naming one type on extract_logs, extract_all_logs and export_logs_to_file, alongside the list. Both are shapes the wire itself accepts: extractlog's type takes a JSON array, or a plain string for a single type. Verified directly — "AUTH", ["AUTH"] and ["AUTH", "SESSION"] all return 200. The single-type case is written as a bare string throughout the API documentation and the Postman collection, so it was the natural thing to pass and used to be rejected. Each value is still validated against VALID_LOG_TYPES and still goes through the space-name wire translation. validate_log_types() now agrees with what extract_logs accepts — a bare "AUTH" returns True where it previously returned False.
  • A comma-joined string is refused rather than split. "AUTH,SESSION" raises ValidationError naming the fix. The platform reads it as one unknown log type and rejects it, so accepting it here would create an input that works only through this SDK — code written against it would break the moment it was carried to curl, Postman or any other client. validate_log_types("AUTH,SESSION") returns False for the same reason.
  • One further contract change on the same method: validate_log_types([]) now returns False where it previously returned True. The old implementation ended in set(log_types).issubset(VALID_LOG_TYPES), and the empty set is a subset of everything, so an empty list validated successfully and then failed at the call it was validating for. The new answer is the correct one, but it is a silent change to a public classmethod and is called out here rather than left to be discovered.

  • One API command that had no SDK method, closing a substantive gap in command coverage. It existed on the server and was reachable with a hand-built command array; nothing had wrapped it.

  • OrgManagementAPI.get_sso_policy() — the SAML policy view of an org's SSO setup. This is a different server-side object from the Partner SSO record that get_partner_sso_config() returns, and the two are easy to confuse: they overlap in the IdP fields and disagree in what else they carry. The reason to reach for this one rather than the other is what each requires to be switched on: this call needs only SSO enabled, while the Partner SSO call additionally needs the Partner SSO section enabled. An org running plain SAML SSO is readable here and reports "Partner SSO config is disabled" there. Their returns otherwise overlap almost entirely — the same IdP fields and the same Service Provider URLs (SP_entity_id, a8_postback_url, a8_portal_url, all derived from the org's slug at call time rather than stored); the Partner SSO record adds partner_SSO_sign_cert, which this one does not return. Identify the org with org_name or org_id; with neither, the server answers for the org the admin token belongs to. SSO being switched off is reported as an error, not an empty result, and there are two distinct such errors. "No SSO config found for org" means the org has never had a SAML policy configured at all — there is nothing to enable without going through create_partner_sso_config(). "SSO config is disabled" means a policy exists but is currently switched off — enable_partner_sso_config() will restore it. Confirmed empirically against a live SSO-enabled organization, including both error states.

  • One MCP tool wrapping the command above, bringing the server to 76 tools. a8_get_sso_policy joins Organization Management.

  • Postman collection: one new request, with real captured examples. Get SSO Policy joins the existing Organization Management group, recorded against a live SSO-enabled organization — a valid response plus both distinct "no SSO" error states described above.

  • Five commands wrapped and then removed before release, for two different reasons. get_org_attrs and the three commands in an SMS source's lifecycle (register_sms_source, send_sms_source_heartbeat, submit_inbound_sms_message) were confirmed, by live testing against every credential type this SDK configures, not to be callable with any of them — they were never reachable by any caller of this SDK. get_node_config was removed as a scope decision: node provisioning is outside what this SDK carries going forward. Nothing here is a behavior change for existing users: none of the five ever shipped in a release.

  • The docs explain how to find an org's sovereign egress locations. Sovereign egress is provisioned per org, for toolbox-standalone research sessions only. The browsing and MCP docstrings, which used to say only that its locations are not published, now explain how to find them: call list_egresses with session_type="toolbox-standalone" and look for "protocol": "sovereign" in a location's categories. Or pass World with protocol: "sovereign" and let the platform choose.

  • The list_egresses docs explain why an org can list no egress while its users have some. Selecting by org_id or org_name reports the egress provisioned to that org, not to orgs beneath it, so a top-level org whose egress is provisioned to its sub-orgs returns an empty list. The list_egresses and a8_list_egresses docstrings and the browsing reference now say so, and point to username or user_id for what a user can select.

  • a8_create_browsing_url accepts egress_info, as a8_create_context does. Combining it with egress_region or categories is rejected.

  • default_egress_for_task_type() in silo_sdk.utils returns the egress a harvest task gets when none is given: New York City for asset and wget tasks, World for every other type.

Fixed

  • get_proxy_policy() no longer raises for an org that has never had a proxy policy set. The platform answers that case with a status message (No proxy policy set at this org.) instead of {"proxies": [...]}, and the method treated it as an unreadable response. It now returns [], so MCP a8_clear_proxy_policy also returns a count of zero for such an org instead of failing.
  • The MCP server starts from a PyPI install, configured by environment variables alone. load_config() needed a config file in the current directory — config/default.json, config.json or sample_config.json — and raised No configuration file found without one, even with every A8_* variable set. That left pip install silo-sdk-mcp with a server that would not start: there is no config file outside a clone of the repository, and MCP clients launch servers from a directory of their own choosing. The package now carries a copy of the default configuration, which holds only ${A8_*} references, and falls back to it when no config file is found. A config file in the current directory still takes precedence, so existing setups behave as before.
  • A missing token now names the variable to set. The error reads Missing required configuration: ADMIN_TOKEN (set A8_ADMIN_TOKEN) rather than naming only the config key. It is still raised when a client or tool that needs the token is created, not at startup, so a server with only some tokens set runs the tools it can.
  • The MCP server reports its own version to clients. serverInfo.version in the MCP handshake carried the version of the underlying mcp library (for example 1.30.0) instead of the installed silo-sdk-mcp release, so a client log or diagnostic could not tell which release it was talking to. It now reports the SDK version.
  • AddUserResult.bypass_code is typed str | None. add_user() returns None there when the platform issues no bypass code; the type said str.
  • MCP a8_extract_logs with fallback_per_type=true no longer raises when a type succeeds with no rows. The fallback raised whenever the merged page was empty and any type had failed, so an org with no AUTH rows in the window lost the fact that AUTH worked and only ENC failed. It now raises only when no type succeeded, and otherwise returns the page with type_errors.

  • list_egresses() threw away the half of the error that told you what to fix. The new directory endpoint is plain REST, so a rejection arrives as an HTTP status code with an explanation in the body — and the SDK parses that body and attaches it. list_egresses() then caught its own exception and re-raised a new one built from the status line alone, so the explanation was dropped on the floor. Selecting by an organization name that appears more than once in the hierarchy is the case you were most likely to hit: the server answers 400 and says, in as many words, to pass org_id instead, and all that reached the caller was Failed to list egresses: API request failed: 400 Bad Request. The remedy survived only on the __cause__ of the raised exception, which nothing documented suggested looking at. The server's message is now in the error text, and status_code, response_data and request_id are carried through to the raised BrowsingAPIError so you can branch on them directly. Related: an organization name shared across the hierarchy must be disambiguated with org_id — this was not previously documented anywhere.

  • SiloError gained a server_message property, which returns the platform's own explanation from the error body, or None when the response carried nothing usable. message stays what it was: what the SDK was attempting.
  • An error nested inside an otherwise successful result is now raised instead of returned as data. The command-array endpoint does not use HTTP status codes — a rejected command still comes back as HTTP 200 — so the error element is the failure signal, and there are two places it can appear. {"error": ...} in place of result was already raised. {"result": {"error": ...}} was not: the SDK saw a result key, returned its contents, and handed the caller a failure dressed as data. get_context() on a deleted context ID is the case most likely to have bitten you — it returns exactly this shape, so the call succeeded and produced a dict whose only meaningful content was an error string, which code checking for an exception would sail straight past.
  • Action required if you inspected the returned dict for an error key. Calls that previously returned {"error": "..."} now raise SiloError with that message, carrying the full response element as response_data. Code that tested for the key will no longer see it; code that already relied on exceptions gets the failure it was expecting. A result dict whose error is empty or falsey is untouched and still returned.
  • find_files() documented a set of returned fields that the platform does not send. The docstring listed size, created_ts, modified_ts and metadata; the reply actually carries bucket_id, file_id, name, path, type, content_type, file_size, create_user_id, create_username, create_ts, expire_ts, uploading_until and session_id. Anyone writing against the docstring rather than against a live response was reading keys that were never there. The full list is now documented on both the SDK method and the a8_find_files MCP tool, along with the note that results are passed through unfiltered, so a field the platform adds shows up without an SDK change. session_id is the useful one that went unmentioned entirely: it ties a stored file back to the session that produced it, which is what you want when correlating a DVR recording or a download with session activity.
  • The replacement list was itself wrong in two ways, now corrected. It named a single create_user, which the platform does not send — the creating account comes back as two fields, create_user_id and create_username. And it listed session_id unconditionally; that field is absent from records not produced by a browsing session, so read it with .get(). Both were caught by comparing the documented list against the captured responses in the bundled collection rather than against a reading of the API documentation, and a test now pins the full record shape to those captures.
  • The SDK logged every line twice in any application that had already configured logging. The client attached a StreamHandler to the silo_sdk logger whenever that logger had none of its own, without checking whether the root logger — which silo_sdk records propagate to — already had one. A host that had called logging.basicConfig() therefore got both, and each line appeared twice in two different formats. Confirmed in the MCP server's container, which configures root logging at startup, where three API calls produced six API request: lines. The SDK now supplies a handler only when nothing else has, which is the ordinary courtesy for a library: a plain script still gets output, and an application that has set up logging keeps its own format and destinations. If you were relying on the SDK's handler while also configuring root logging, your silo_sdk lines now render in your format rather than both.
  • ConfigBuilder.with_default_policy() wrote a key nothing reads. It set default_policy in lower case, while the shipped config files, a8_validate_config and the bundled examples all look for DEFAULT_POLICY. A configuration built through the builder therefore carried a policy that every consumer silently ignored — no error, just a default that never applied. The builder now writes DEFAULT_POLICY, and the sample configuration file written by create_sample_config() has been corrected the same way. Action required if you read the key back yourself: code doing config["default_policy"] on a builder result will now raise KeyError; read config["DEFAULT_POLICY"].
  • find_files(limit=...) and list_files(limit=...) now return at most limit files. Both documented the argument as a maximum and neither enforced it. The value was sent on the wire and the server ignored it — a bucket holding 109 files answered a request for 2 with all 109 — and nothing on the client side trimmed the result, so the cap was simply untrue and anything paging on it received the entire bucket on every call. The listing is now truncated on arrival. This cannot save the transfer, since the server has already sent the full response by the time we see it; the argument bounds what you are handed, not what crosses the network, and the docstrings now say so rather than implying otherwise. Action required if you were compensating for this: code that sliced the result itself will now be slicing an already-short list, which is harmless, but code that passed a small limit and relied on getting everything back was relying on the bug and will now get limit entries.
  • bulk_download_async no longer lets its concurrency limit exceed the connection pool it shares. The batch runs on one HTTP client, and that client's pool defaults to 100 connections with 20 kept alive — so a max_concurrent above those numbers bought no extra parallelism, it queued downloads inside the pool where nothing surfaced the wait. The pool is now sized to the requested concurrency, and max_concurrent above 100 raises ValidationError rather than opening that many sockets.

  • find_harvest_task() documented four timestamp fields it has never returned, and a task status the platform has never sent. Its Returns: section named created_ts, started_ts, completed_ts and task_metadata; the method passes the platform's record straight through, so the real names are create_ts, start_ts, end_ts and task_results, and reading any of the four documented names raised KeyError. Only wait_for_completion_async() adds those aliases, layered on top of the raw record — wait_for_completion() does not, despite polling the same call. All three Returns: sections now say which shape they hand back and enumerate every field that arrives in it: identity and state, the epoch-float timestamps, what was requested, and the results. Two of those fields do not mean what their names suggest — hostname is the worker that claimed the task, not the target being harvested, and attempt_count includes the attempt currently in flight.

  • There is no running task status. It was documented as one of five for a long time and the platform has only ever sent four: wait, claimed, done and error. A task that is actively executing reads claimed, so any caller branching on "running" — to render a spinner, to decide a task was live, to filter a list — silently never matched and fell through to whatever its else-branch did. The status is corrected in the TaskRecord type, in the harvest how-to guide, in the SDK docstrings and in the MCP tool descriptions for a8_find_harvest_task, a8_list_harvest_tasks and a8_wait_for_harvest_task. The SDK keeps "running" in four internal membership tests as a deliberate defensive extra, so a future in-progress status cannot fall through to the unknown-status error; each is now commented as such, because an uncommented list of status strings is exactly what the documentation was copied from.
  • The TaskRecord type declared nine keys for a record that carries twenty-two, and three of the nine were the aliases only one of its three listed methods produces. It now declares both spellings, says which methods emit which, and covers the full record — so task["hostname"] and task["create_ts"] type-check instead of being reported as unknown keys.
  • The return-contract guard now also checks the opposite direction: fields the platform sends that no docstring mentions. A Returns: section promising a field the wire does not send fails loudly as a KeyError, which is why that direction was guarded first. The reverse never fails at all — the field arrives, the documentation omits it, and callers simply never learn it is available. Three such gaps were found by hand in a single evening and are fixed in this release; all three would have been caught automatically. All eighteen checked methods now document every field they receive — the two harvest-task methods were the last holdouts at thirteen and twelve omitted fields each, and are completed in this same release (see below). Renames are declared once as a documented-name/wire-name pair, so a renamed field is no longer reported as missing by one check and undocumented by the other.
  • The return-contract guard now accounts for every method it cannot check, by name. Eight methods have a captured response but no bullet-list Returns: section, and the bare count invited the conclusion that they were pending documentation work. They are not: seven return a str or a bool, so there are no field names to list, and the eighth returns the list nested inside the response rather than the response itself. Converting that last one to bullets would have compared its documented names against a record whose only top-level key is the wrapper, reporting five fields the platform really does send as though they were absent. The guard now fails with that explanation if anyone tries, rather than producing five convincing false findings, and a new method that genuinely lacks a field list fails by name instead of merely changing a total.
  • The return-contract guard was exempting whole methods, and hid a real defect doing it. Two harvesting methods were excluded from the check because they legitimately rename four wire fields — but the exclusion was per method, so it also suppressed every genuine ghost in them. One was there: a documented worker_id the platform has never sent. Exemptions are now per field, so the four renames stay exempt and anything else in those methods is compared. A second gap is closed alongside it: a bullet written as -field(list): ... did not match the parser, so delete_proxy_policy's Returns section parsed to zero fields and was silently unchecked. The guard now covers 18 methods rather than 13 — without a single docstring being rewritten, because five of those were only ever counted as covered.
  • get_proxy_policy() reported that every organization has no proxies. The platform wraps the list as {"proxies": [...]}; the method accepted only a bare list, so the unwrapping branch was never taken and every call returned [] — for orgs with proxies configured as readily as for orgs without. No exception was raised and the log line read "Retrieved 0 proxy objects", so a caller had nothing to notice. The wrapped shape is now read, and a response that cannot be read raises OrgManagementAPIError instead of returning []: "could not parse this" and "no proxies are configured" were previously the same answer, which is what kept the defect invisible. Action required if you branched on an empty result — code that concluded "no proxy policy" and skipped ahead will now see the real list.
  • The existing test passed throughout, because it mocked a bare list — a shape the platform has never sent. The mock had been written from the SDK's own assumption, so it could only ever confirm that assumption. Both proxy-policy tests are now built from the response saved in postman_examples/.
  • set_proxy_policy() had the same defect and is fixed the same way, which changes its return type. The platform confirms with the string "Proxy policy successfully overwritten"; the method tested for isinstance(result, list) and so returned [] on every call. It now returns str, matching add_proxy_policy(), which has always returned its confirmation string. This is a signature change, and it breaks nothing that worked: the previous return value was the constant [] for every input, so no caller can have been reading anything from it. Type annotations and list-shaped assertions are the only things affected. Call get_proxy_policy() to read back the resulting list.
  • add_proxy_policy() and delete_proxy_policy() were checked against the captures and are correct — all four methods in the family were examined, not just the two that looked wrong.
  • update_org() promised "the updated organization details" and returns two fields. The response carries exactly org_id and org_name; vanity_url, the parent references and the timestamps are absent even when the call just changed them. The docstring now lists the two fields and points at get_org() for reading back a change.
  • get_user() and list_users() documented about two thirds of what they return. get_user() omitted is_locked, failed_login_attempts, oob_locked and oob_lock_expires_at, so there was no documented way to tell a locked account from a suspended one; list_users() omitted create_ts, last_authorized_ts and custom_fields. Both lists are now complete, and list_users() states that its record is not the same shape as get_user()'s — the lockout fields are absent from the list response, so checking lockout state means a call per user.
  • find_harvest_task() handed you the server's error as though it were a task. 0.15.0 made a reported error raise rather than return (see An error nested inside an otherwise successful result below), but this method caught that exception alongside genuine parse failures and fell back to returning the raw response element. Both shapes the endpoint uses to report failure — an error in place of the result, and an error nested inside a result — therefore arrived back at the caller looking like task details. The envelope has no status, so it was written into the status cache as a real task, and wait_for_completion() reported Unexpected task status: None some time later instead of what the server had said at the point of failure. An invalid harvester token was the likeliest way to meet this: the platform names the problem clearly, and none of that reached you. Both shapes are confirmed by live API testing against this command and are now covered by tests using the observed response bodies.
  • Two callers were wrong for the same reason and are now correct. The MCP diagnostics probe reported an invalid harvester token as a successful probe, because the error envelope it got back was truthy. a8_list_harvest_tasks appended those envelopes to its results, so a listing could contain entries that were not tasks.
  • Action required if you tested the returned dict for an error key. A lookup that previously returned {"error": "..."} now raises HarvesterAPIError carrying that message. Code that already relied on exceptions gets the failure it was expecting.
  • The fallback path is kept for genuinely malformed responses; this narrows it to those rather than removing it.
  • Multi-type log extraction never worked, and now does. The platform takes extractlog's type as a list; this SDK joined the requested types into a comma-separated string, which the server parses as one unknown type and rejects with ValueError: invalid log type. Only single-type calls survived that, because a one-element join has no comma in it — so extract_logs(log_types=["AUTH", "SESSION"]), the shape the docstrings have always shown, has been failing since the method existed, and extract_all_logs inherited the same break. Verified against production with one token and one org: a list of two types returns entries of both, while comma-, pipe- and space-joined strings are all rejected. Action required if you worked around this by issuing one call per type and merging the results — that is no longer necessary, though it still works.
  • The error had been recorded in the test suite as a token-scope restriction with the note "the SDK wire format is correct". It was not correct; the encoding was wrong. Those tests and their rationale are updated rather than deleted, so the wrong explanation does not get rediscovered.
  • The Postman collection's multi-type log requests only ever sent one type. Five requests in 5. Log Extraction were named for a combination but carried a single type in the body — "AUTH + SESSION" sent AUTH, "URL + Blocked URL" sent URL, "Security Events (EXPLOIT + CLIPBOARD)" sent EXPLOIT, "Download + Upload" sent DOWNLOAD, and "Extract All Log Types" sent AUTH rather than all 26. Each now sends a JSON array of the types it is named for, and all five were re-run against a live environment to confirm they return 200 with entries of every requested type. The folder description now states that type takes a string or an array, and that a comma-joined string is rejected as an unknown log type.
  • The saved Error: unknown log type example asked for URL while its recorded response complained about NOSUCHTYPE; its request now sends ["URL", "NOSUCHTYPE"], and the response it carries is byte-identical to what that request returns today.
  • Docstrings described the wire format as a comma-joined string in four places on extract_logs and the shared normalizer, including one line that contradicted the list example printed directly beneath it. They now say JSON array.

  • a8_extract_logs's per-type fallback handed back a resume point that skipped rows. With fallback_per_type=True, a failed multi-type extraction is retried one type at a time and the results are aggregated. Each type paginates independently, so they finish at different sequence numbers — and the aggregation returned the highest next_seq it had seen. If AUTH reached 5000 while SESSION only reached 2000, the caller was told to resume at 5000 and every SESSION row between 2000 and 5000 was never fetched. Nothing errored; the rows were simply absent. It now returns the lowest resume point among the types still reporting is_more, so a resumed page will repeat rows for every type whose own next_seq was higher — so deduplicate by seq_id when paging a fallback response. That is the deliberate trade: duplicates are visible and recoverable, gaps are neither. When no type reports more, next_seq is the lowest next_seq any type reported, so a poller keeps advancing; types listed in type_errors must be re-requested from the original start_seq.

  • The fallback itself is worth keeping and is not deprecated. It was originally a workaround for multi-type extraction being broken, which is fixed above — but it still covers the case it was never really about: one log type failing server-side while the rest succeed. An org without encryption enabled rejects ENC with a clear message and extracts every other type normally, and the fallback is what returns those.

  • The SDK blocked two harvest parameters and one task type the platform accepts. The compiled parameter allowlists otherwise match what the platform accepts — no parameter is invented, and nothing the SDK sends would be rejected — but translation_proxy was missing from both VALID_VISUAL_PARAMS and VALID_VIDEO_PARAMS, so a visual or video task setting it failed locally before any request. wget is likewise a task type the platform accepts, and was rejected. Both are now accepted. wget shares asset's parameter family and wire shape, differing only in request_type (see Changed for how wget is validated).

  • One definition, three gates. VALID_TASK_TYPES existed as a hardcoded literal in three places — the class attribute, the task builder and validate_task_config. Adding a type to one left the others rejecting it, so a caller could be told the same type was both valid and invalid depending on which surface answered. There is now a single definition in silo_sdk.utils.harvester_utils, which the other two reference, and a test asserting every gate accepts every canonical type.
  • render is deliberately still refused. The platform accepts it, but marks it an invisible type that its own find command cannot return — a task created with it could not then be retrieved through this API. That is a question for the platform rather than a gap to close.

  • Three MCP tools could not reach settings their SDK methods have always had. a8_create_research_session had no way to set policy or expires, so a research session launched through MCP ran under the org's default policy with no expiry and no way to change either — while a8_create_context, wrapping the same underlying operation, exposed both. a8_create_context in turn could not set auto_domain_allow. All three are now available on both tools. Neither omission was deliberate, which is the point: nothing would have caught them.

  • A test now enforces the parity. Every MCP tool must expose every parameter of the SDK method it wraps, or name the omission with a reason. Two are recorded as deliberate: a8_create_research_session flattens browser_profile and categories into scalar arguments that suit flat-argument callers, and a8_batch_request takes a token_type rather than an auth_token so raw tokens stay off the MCP surface. Anything else fails the suite and says which tool and which parameter.

  • get_file_info() documented a scoped lookup it never performed. Its docstring said it used "a file_id-scoped findfiles lookup, rather than fetching the entire bucket listing", and an inline comment credited that with avoiding a failure where a server-side cap on the listing makes an existing file report as missing. The server ignores file_id there, as it does the size bounds above, so the full listing always came back and the cap risk was never mitigated. The method still returns the right answer, so nothing failed — but the next reader would have trusted the claim. Both now describe what happens, and the remaining cap risk is stated as a warning rather than implied to be solved.

  • upload_file() documented six return fields where the upload endpoint sends one. The docstring promised file_id, name, path, size, content_type and upload_ts; the endpoint returns file_id alone, and the method passes the response body through unchanged. Reading any of the other five raised KeyError for anyone who trusted the documentation. Unlike the two entries above, this one published a return contract rather than describing an internal mechanism — a caller who believed it crashed. The Returns section now documents the single field, with a warning naming the five that were never sent and pointing at get_file_info() for the rest of the record.

  • The tests had encoded the same fiction. The upload mock invented the missing fields and the suite asserted against them, so full coverage confirmed the documentation instead of the API. The mock now returns what the endpoint returns, and a new assertion pins the response to exactly one key so the invented fields cannot quietly return.
  • File-search mocks used size and id, which the API does not send. Search results report file_size and file_id; six mocks across the SDK and MCP suites had the wrong names. No behavior changes — the fixtures now match the wire, which is what makes them worth having.
  • Every harvest task timestamp was None, and the values were in the response all along. find_harvest_task() and everything built on it — wait_for_completion(), the progress helpers, a8_find_harvest_task — reported created_ts, started_ts and completed_ts as None on every call. The SDK read those three names off the server record, but the wire sends create_ts, start_ts and end_ts, so all three lookups missed and returned nothing. No error, no warning, and HarvestTaskInfo declares them as required strings, so the documented contract had never once been met. The names are now translated, and a task's real creation and start times come through; completed_ts is null until the task finishes, which is the server's own answer rather than a miss.
  • There is no progress field and there never was. The docstring offered one "if available", and the platform reports task state through status and finished only — it sends no percentage. Anything reading progress gets None every time. Every place that claimed otherwise now says so: the find_harvest_task summary and Returns, its example code (which demonstrated reading the field), HarvestTaskInfo, a8_find_harvest_task, and the workflow tool's documented response. The field itself is retained, since removing a declared key breaks callers who type-check against it.
  • A second fault was hidden behind the first. wait_for_completion_with_progress() passed the non-existent value into TaskProgress.update_status() positionally, where the second parameter is message, not progress — so a server that did report a percentage would have set it as the status message. The two mistakes cancelled out only because the value never existed. The argument is no longer passed.
  • HarvestTaskInfo's timestamp types were wrong in two ways. created_ts, started_ts and completed_ts were declared as required str. They are Unix epoch floats, and the latter two are None until the task is claimed and finishes respectively. Now float | None.
  • add_user() reported a failure after successfully creating the user. When no bypass code is issued, the command announces success as a plain string rather than as the object it returns in every other case. add_user() accepted only an object and raised UserManagementAPIError: Unexpected result format: user added for anything else — so a creation that had fully succeeded, audit entry and all, arrived back at the caller as an error. This is the more damaging direction for a false result to point: the natural response to a failed create is to retry it, and the retry lands on an organization where the account already exists. The success string is now recognized and returns the documented shape with bypass_code set to None.
  • Matched exactly, deliberately. The same field carries a probable error: ... string when the creation genuinely did not happen, and a looser test — any string, or a prefix match — would convert those into reported successes, which is the failure this change is meant to prevent, inverted. Only the exact success string is accepted; every other unexpected result still raises exactly as before, and that behavior stays covered by its own test.
  • bypass_code can now be None on success. The key is always present in the returned dictionary. Test the value, not the key — if "bypass_code" in result no longer tells you a code was issued, and result["bypass_code"] may be None on a creation that worked.
  • Five more methods documented return fields the platform does not send. Each is a broken return contract rather than a wrong explanation: the documented key is absent from every real response, so reading it raises KeyError. Several were a single character away from correct, which is why they survived review.
  • get_org() listed created_ts, user_count, settings and parent_org. The record carries create_ts, current_users and provisioning_info, and the parent comes back as two fields, parent_org_id and parent_org_name. No settings sub-dict exists — the a8_get_org tool went further and documented settings.proxy_policy, settings.allow_list, settings.deny_list and settings.session_type, none of which appear in any response. Use get_proxy_policy() / a8_get_proxy_policy for an org's proxies.
  • get_org_children() listed created_ts, user_count and depth. The listing carries current_users, provisioning_info and vanity_url, and reports no creation timestamp and no hierarchy depth at all. (The a8_list_child_orgs tool does return a depth field, but it computes that itself when recursive=True; it does not come from the platform.)
  • create_org() promised vanity_url and created_ts. The create response contains org_id and org_name and nothing else. Call get_org() with the new org_id for the full record.
  • extract_logs() listed total_count, org and log_types alongside the three real fields. The response is logs, is_more and next_seq only. There is no total — the endpoint pages, and is_more is the only answer to whether more rows exist.
  • get_context() listed created_ts, expires_ts and policy; the real names are create_ts and expires, and the configuration comes back under context_data. Nine further fields the context record does carry — including enabled, last_use and commonality — were undocumented and are now listed. The a8_get_context tool repeated the same three wrong names.

  • wait_for_completion_async() documented a worker_id field the platform has never sent. It named the field as server-reported, so the rename explanation covering the other normalized names did not apply to it. The field that reports which machine ran a task is hostname. The Returns section now lists the real pass-through fields, split from the normalized ones, so the two halves of the merged result are distinguishable.

  • The comment justifying that merge cited two fields that do not exist. It explained the raw dict merge as recovering "fields like progress/task_params/worker_id" — of which only task_params is real. A reader checking whether the merge was necessary would have gone looking for progress in a response and found nothing. It now names fields the server actually sends: task_params, attempt_count, hostname, finished, target, task_results.

  • a8_health_check was under-reporting what an admin token unlocks. Its capabilities map names the tools each configured token makes usable, and the six tools above were missing from it — so a caller asking the server what it could do with the credentials it had been given would have been told six fewer things than the truth. Found by the existing coverage test, which compares the map against the live registration list rather than against a count.

  • Response redaction now masks every key the request logger masks. The two lists had drifted: a request masked any parameter whose name contained key, while a response only masked api_key, apikey and private_key. Anything else — ipsec_key, for one — was rendered in full in the "unexpected response format" warning and in the SiloError message that accompanies it. The response list is now derived from the request list rather than restated, so adding a term to one cannot leave the other behind, and a test pins that containment. Affects any response, not just the new commands; the visible effect is that a few more field names render as <redacted> when the SDK reports a shape it does not recognize.

  • Harvest tasks no longer default to an egress asset and wget tasks reject. TaskBuilder, create_simple_task and bulk_create_and_monitor_async gave every task New York, NY, which is not one of the six datacenter locations asset and wget tasks accept. With no egress given, they now use New York City for asset and wget tasks and World for other types. A location you set, or a bulk-level egress_info, still applies. The sync and async harvest demos send New York City to their asset tasks, and the egress_info docs on the harvester methods note the asset and wget location limit.

  • The async harvester reports server errors. wait_for_completion_async read an error in place of the result as "no result yet" and polled until timeout, and failed on an error nested inside the result with Failed to monitor async task: 0. Both now raise HarvesterAPIError with the server's message on the first poll, as wait_for_completion does. create_harvest_task_async reported a rejected task as Unexpected response format with the raw response; it now raises with the server's error message.

  • create_context() and get_context() keep the server's error message. An error nested inside the result was reported only as Failed to retrieve context ID or No context data found. The BrowsingAPIError now carries the server's message, for example for a deleted context.

  • create_sample_config() writes DEFAULT_EGRESS_INFO instead of the unused DEFAULT_EGRESS_TAG, matching config/default.json.

  • get_session_report(org_name=...) takes a path below the token's own org, and the docs now say so. The server resolves org_name relative to the org the token belongs to, so passing that org's own name — which the docs implied, and which scripts/session_report.py did by default from A8_TOP_ORG — has always been refused with PermissionDenied. Omit every identifier to report on the token's own org; give org_name only for a child org, as "Sales" or "Sales/EMEA". The docstring, the a8_get_session_report MCP tool description, the Postman request and the script are corrected accordingly.

  • scripts/session_report.py no longer reads A8_TOP_ORG. With no --org it now reports on the token's own org; --org takes a child org path.
  • hierarchy=True does not change the result. Child orgs are included by default, with or without org_name, which live API testing confirms. The flag is kept for compatibility and documented as such.

  • The bundled scripts in scripts/ now honor A8_CONFIG_ENV. Each one loaded config/default.json by explicit path, which skips the selected profile's own config file (config/<profile>.json). A profile that maps its tokens there, rather than through A8_* variables, was silently ignored, and the script ran with whatever tokens .env held. They now call load_config(), which applies the profile. export_logs.py and scheduled_visual_harvest.py also read A8_TOP_ORG, or the scrape and file tokens, straight from the shell before loading the config. A value set only in .env, .env.<profile> or a profile's config file failed their checks. They now read these from the loaded config.

  • The examples in examples/ now honor A8_CONFIG_ENV too, and no longer print part of a token. The demos loaded config/default.json by explicit path, with the same effect as the scripts above. They now call load_config(), and config_demo.py shows that instead of loading config/<profile>.json on its own, which never merged it with the base config and failed for a profile with no file of its own. config_demo.py also printed the first eight characters of every token it found; it now prints only whether each one is set. The "missing token" hints point to .env rather than config/default.json, which is version-controlled and must hold only ${A8_*} references.

  • The configuration docs no longer claim an unset ${VAR} raises ConfigurationError. It never did. Substitution replaces an unset variable with an empty string, and load_config() succeeds. A missing token is reported only when a client that needs it is constructed, as Missing required configuration: <KEY> (set A8_<KEY>). The configuration guide now says so, and also documents the ${VAR:default} form (identical to ${VAR:-default}), the empty-variable fallback, inline placeholders, and the forms that are not recognized ($VAR, ${VAR-default}). No code changed.

  • The load_config() docstring no longer lists environment variables as a priority level of their own. It placed them below both config files, as if a variable could supply a key the files left out. It cannot. A key's value comes from the profile file, then config/default.json, then the built-in defaults; a variable only fills a ${VAR} placeholder inside whichever value wins. A placeholder that resolves to "" is handled by key type: a numeric key is removed, so its built-in default applies; a boolean key reads as false; any other key, such as API_URL, keeps the empty string, and no built-in default replaces it. The docstring and config/README.md now say so. The examples README, the examples page and the examples/config_demo.py text no longer say variables are substituted into config/default.json: substitution runs once, after the profile file is merged over it, so placeholders in either file are resolved, and the configuration guide now states that order. A broken link in config/README.md to a nonexistent examples/config/ directory is replaced with links that exist. No SDK behavior changed.

  • The MCP server's credentials.yaml substitution falls back to the default for an empty variable. ${VAR:-default} resolved to "" when VAR was set but empty, because only an unset variable fell back. It now behaves like load_config() and bash: an empty variable uses the default too. This affects the HTTP transport, which reads credentials.yaml; the stdio transport already used load_config().

  • scripts/key_manager.py no longer prints any part of a stored key or token. list-keys showed the first and last characters of each key, and show-token showed the first eight and last four characters of the token — or the whole token when it was 16 characters or shorter. list-keys now shows only whether each key is set, and show-token reports that a token is stored and where. pvtkey.txt and token.txt are also now written readable by their owner only (mode 600), including when the file already existed with wider permissions.

  • Asset harvest examples in the HarvesterAPI and TaskBuilder docstrings and the bulk harvest guide use an asset egress location. They passed "New York, NY", which is not one of the six datacenter locations asset tasks draw from, so copying them produced an egress warning. They now use "New York City".

  • An invalid A8_CONFIG_ENV is no longer used to build a .env file path. load_config() already rejected a profile name containing anything but letters, digits, hyphens and underscores, but only after it had loaded .env.<name>, so a value such as sub/leak could load a file outside the intended name pattern before the error. The name is now checked first, and load_config() called without a path raises the same ConfigurationError. An A8_CONFIG_ENV set inside .env.<profile> no longer switches the profile either. It used to change which config/<profile>.json was merged after .env.<profile> had been chosen by the original name, so the two came from different profiles.

  • The docs and .env.example describe where A8_CONFIG_ENV can be set. They said it must come from the shell, that it could not be set in .env, and that it defaulted to production. There is no default profile. A value in .env selects the profile, and one exported in the shell takes precedence over it. The configuration guide, README.md and config/README.md now also note that for every other variable, a value in .env replaces one exported in the shell. examples/config_demo.py now reports the profile after loading the config, so a profile set in .env is shown rather than (none).

  • The script docs no longer say org_usage_report.py, user_usage_report.py and audit_org_users.py read A8_TOP_ORG. All three take a required --org and ignore the variable. The published scripts page now matches the scripts README: it documents create_context.py, drops a maintainer-only script that is no longer in scripts/, says A8_BUCKET_ID belongs in .env rather than config/default.json. The scripts README's scheduled_visual_harvest.py example now uses "Dallas, TX", which the script accepts, instead of Dallas, which it rejects.

  • The bundled scripts' missing-token message mentions profile files. It now reads Set A8_X_TOKEN in your .env (or .env.<profile> for A8_CONFIG_ENV).

  • A8_TARGET_ORG now reaches scripts/move_users.py. The script and its docs used it as the default destination org, but config/default.json never mapped it, so it was always empty. config/default.json now maps it to TARGET_ORG.

Changed

  • wget harvest tasks now get asset's rules everywhere, because that is what they run as. The platform accepts wget and then runs it as an asset task, converting it before any parameter check or egress lookup, so every check that applies to asset now applies to wget too:
  • Egress. TOR egress is rejected for wget as it is for asset, and a location outside the six asset egress locations now produces the same warning. The per-location connectivity/protocol cross-check is skipped for wget, as for asset, since the asset pool is selected differently.
  • all_files is rejected for wget as it is for asset.
  • Parameters and builder options. get_valid_params("wget") returns the asset parameter set instead of raising, validate_task_params() no longer rejects wget as an unknown type, and TaskBuilder("wget") accepts .recursive(), .level() and .timeout(). create_simple_task("wget", ..., timeout=...) no longer drops the timeout.
  • Three new constants name these groups so they stop being re-typed as literals: WGET_PARAMS_TASK_TYPES (asset, single, wget — every type sent with wget_params), ASSET_TASK_TYPES (asset, wget), and, for task status, ACTIVE_TASK_STATUSES and IN_PROGRESS_TASK_STATUSES, all in silo_sdk.utils.harvester_utils.

  • VALID_TASK_TYPES is a frozenset. It was a mutable set shared by every gate that checks task types, so mutating it changed what all of them accept. HarvesterAPI.get_valid_task_types() still returns a fresh set.

  • UploadResult now describes only file_id, because that is all upload_file() returns. The type also listed name, path, size, content_type and upload_ts, none of which are in the upload response, so code written against the type would read None or raise KeyError. Pass the file_id to get_file_info() for the rest of the record (FileInfo). Only type annotations and code that read the missing fields are affected, and that code was already broken.

  • The duplicated flow folders in the bundled Postman collection are merged. Every domain carried two lifecycle folders — a Flow: … set and a [Flow] … set — 52 of the collection's requests between them, with neither a superset of the other: one had the variable-priming setup steps and the admin operations, the other the retrieval and download steps. Anyone following a flow got whichever half they happened to open. There is now one folder per domain holding the union, and the collection is 97 requests rather than 120 (99 after the sub-org steps below). No coverage was lost: the four requests unique to the removed set (Update Org, Promote User to Admin, Get File Info, and the log-paging Extract Next Page) were moved across, and the separate Setup requests are gone — each flow now primes its own variables in the first request's pre-request script, which also removes one API round trip per flow. The context flow shipped with no assertions at all on its surviving copy; it now carries the resource-specific checks the other copy had.

  • The Postman collection now demonstrates creating an org beneath a newly created org. Every org.create in the collection parented the new org off the org_name already in the environment, so the parent/child chain — create an org, then create a child of that org using the org_name the server returned — appeared nowhere, despite three separate requests creating an org. The org lifecycle flow gains FLOW — Create Sub-Org, which reads org_id/org_name out of the previous response rather than from configuration, and FLOW — Delete Sub-Org, which is not optional: the platform refuses to delete an org that still contains sub-orgs, so without it the flow's own cleanup step fails. The collection is 99 requests.

  • The Postman collection's pre-request guards check the variables each request actually uses. Every request validates its required environment variables before sending, and 37 of those lists were wrong — 23 named a variable the request never interpolates while missing one it does. Download File, Modify File Metadata and Delete File demanded bucket_id and used file_id; the whole user-management folder demanded org_name for calls that address a user by name alone; two org flow steps demanded org_id for calls keyed on org_name; and two requests had an empty list, so they validated nothing. The effect was a request refusing to send over a variable it did not need, while the one that was actually missing produced a server-side error instead of a clear local one. Base-URL variables (api_url, getfile_url, putfile_url, egresses_url) are deliberately excluded: they come from the environment file rather than from anything the caller sets per request.

  • The SDK no longer refuses an egress the platform is willing to serve. Until now, picking a location together with a connectivity, availability or protocol was checked against a table of per-location capabilities compiled into the SDK, and a combination the table did not record raised ValidationError before any request was sent. That table was a placeholder from a time when there was no way to ask the platform what a caller could use. There is now — list_egresses() — and the placeholder had drifted: live testing found five of nine currently-valid combinations refused by the SDK, on both create_harvest_task() and create_context(). A location whose connectivity changed after the release accounted for most of them, and because the check rolls capabilities up the hierarchy, one stale city also took down its country and its region. The failure mode is the bad one — the SDK saying no to work the platform would have accepted, with a message asserting the combination is unavailable, which reads as fact rather than as the guess it was.
  • What now raises, and what now warns. Anything structural still raises, because it is stable and knowable offline: a missing or blank name, a non-dict egress_info or categories, a category value that is not one of the accepted strings, a non-string where a string belongs, and the mutually-exclusive-parameter checks. Anything about availability — is this location real, does it offer that connectivity, that protocol, is it one of the six asset locations — now emits a logging.WARNING on the silo_sdk.harvesting.egress_validation logger and lets the request proceed to the platform, which is the only party that actually knows. The warning says plainly that the request was not blocked and that the reading came from a table that can lag. Action required if you relied on the refusal: code catching ValidationError around these calls to detect an unavailable egress will no longer see it; the platform's own rejection arrives instead, from the API call. Code that was working around the false refusals can drop the workaround.
  • get_valid_tor_egress_names() returns the 18 names the SDK records as supporting TOR, not all 99 locations. It previously returned every location name regardless of protocol, which made it useless for the one question it names in its own signature. It is still a compiled-in list and still not filtered by entitlement.
  • Two location records were corrected against live data while this was written — one whose connectivity had moved to datacenter, one that carried no connectivity at all. Both are recorded with the date they were verified. The table is now documented as a naming and offline reference rather than an authority, and it is no longer the thing standing between you and a request.

  • a8_list_egress_categories and the harvest tool's egress_info documentation point at a8_list_egresses as the authority on what an account can use, and describe the static lists as compiled-in references that can lag and are not filtered by entitlement. Entitlement varies per user, not just per org, which no static list can express.

  • a8_get_valid_log_types asks the platform instead of reporting the SDK's built-in list. The tool exists so a model can discover what to pass to a8_extract_logs, and a compiled-in list quietly answers a slightly different question than the one asked. It now calls get_log_types() and falls back to the built-in list if that fails — no log token configured, or the platform unreachable — rather than erroring out, since a slightly stale list is more useful to a caller in that spot than no list at all.

  • categories["protocol"] rejects a list with an error that says why. A list was valid in an older revision of the API and still appears in older examples, but a single string is what is accepted now. The SDK already rejected the list; the message said only "must be a string or null", which does not tell a reader their sample is out of date. It now names the case and suggests the first element as the value to pass.
  • The bundled Postman collection covers the commands added here. Unlock User, Get Log Types, List Egresses, and egress_info and sovereign examples on context creation bring it to 120 requests (since reduced to 99 by the flow-folder merge described under Changed). List Egresses is the one request in the collection that is not a command-array call, so the collection README gains a section on the bearer-header scheme it uses, and each environment file gains an egresses_url variable — the existing api_url carries an /api/ prefix the REST endpoint does not sit under.
  • Eighteen requests gained saved example responses, and most of the new ones are failures. Twenty-one examples in all, every one a real reply recorded against a non-production deployment rather than hand-written, so the error text and the field names are the platform's own. Failures are the half a collection usually omits and the half you need, because on this API a rejected command still returns HTTP 200 and the only way to recognize one is to have seen the shape: an error element beside result, an error string nested inside result, a bare 0 from an update that matched nothing, an empty list from a search that found nothing, and — for the /ctx shorthand, which is not a command-array call — an actual 400 with an HTML body. Among them is a harvest task that was accepted with a task_id and only failed at execution, its last_error naming an egress the platform could not provision; that record is what the Changed note above means by the platform being the only party that knows. Every identifier, address and org name is a placeholder.
  • File listings are documented as containing directories. find_files and list_files return directory entries alongside files, distinguishable by a content_type of Folder, and a directory cannot be downloaded — feeding one to download_file or bulk_download_async gets an API error back. Neither docstring mentioned it, so the natural thing to write, downloading everything a listing returns, fails on a fraction of the entries for a reason the documentation gave no hint of. Filter on content_type before downloading. The listings themselves are unchanged: directories were always in them, and dropping them here would break anyone who walks a bucket structure with these methods.
  • bulk_download_async's use_chunked argument is documented as the trade-off it is. The two per-file paths differ in more than chunk size: the default buffers each response in memory before writing but retries transient failures, while use_chunked=True streams to disk with bounded memory and has no retry loop, so a dropped connection simply fails that file. The docstring now says so, and says which to reach for. The default is unchanged — flipping it would have removed retries from every existing bulk download without the caller asking.
  • Bulk and workflow async methods are no longer tagged as async variants of a sync method. bulk_download_async, process_harvest_workflow_async and bulk_create_and_monitor_async were tagged ASYNC_VARIANT with a sync_of naming a method they merely call rather than one they are the async form of — bulk_download_async is not an async download_file, it is a concurrent orchestration over many of them. A new ASYNC_CONVENIENCE method type describes async-only orchestration with no sync counterpart, and these three now carry it along with a wraps list of what they actually drive. This affects the method inventory and anything else that reads the tags; it is not a behavior change to the methods themselves.

  • COMMAND_REGISTRY gains the one entry above.

  • The docstring-versus-captures guard now ignores derived examples. It exists to catch a documented return field that no real response has ever contained, and it can only do that because the thing it compares against was written by the server rather than by us. A derived example is written from the same reading of the server as the docstring it would be checked against, so agreement between the two is not evidence of anything — but it would be reported as a pass. Requests whose description carries the derived marker are therefore skipped. The module says so in its own list of limitations, alongside the others.

  • The bundled Postman collection runs on any org, and its tests catch errors they used to pass. Requests that hardcoded one org's egress locations now read them from four new environment variables: egress_location, isp_location, sovereign_username and sovereign_location, each with a fallback when left empty (World, World, username and World). The sovereign request sends World with the sovereign protocol, so the platform chooses among the org's sovereign locations, and Create Asset Collection Task uses New York City, one of the datacenter locations asset tasks take. The platform returns some errors as {"result": {"error": ...}}, which the "Result present" check passed; every request that checks for a result now also fails on an error inside it, and each create-context request asserts that it returned a browse_context_id. The exception is Create Research Context — Sovereign Egress with sovereign_username empty: its own test then accepts the egress error instead, but the folder-level error check still fails it, so on an org without sovereign egress that request reports a failure. Requests that ran after the object they needed was deleted, or read a variable no environment sets, are reordered or now use the objects the run creates. New saved examples show List Egresses selected by orgname and its current 400, 401 and 403 error bodies, and a log extract made up of SESSION records. The Create Context descriptions note that a successful create does not prove the egress can be served. Every Create Research Context request now stops with a clear message when admin_token, username or url is empty, instead of sending a request the platform rejects.

  • Methods that returned an empty result on a server error now raise. The platform returns a rejected command with HTTP 200, sometimes with the error nested as {"result": {"error": ...}}. Three methods read that as success:

  • extract_logs returned it as a page with no logs, so extract_all_logs stopped paging and reported success, and get_log_sequence_info reported no logs. Both now raise LogExtractionAPIError with the server's message. extract_logs_per_type records the error in type_errors for that type and still returns the others.
  • find_files and list_files returned [], the same as an empty bucket, for an error or for any result that is not a list. They now raise FileAPIError; an empty bucket still returns [].
  • resolve_org returned every error message, including invalid-token and No org matching errors, as a single entry in candidates, and resolved a nested error to the name passed in with an empty org_id. It now raises OrgManagementAPIError, as its docstring said. For an ambiguous name, candidates holds the matching org paths taken from the server's message rather than the message itself.

  • An unknown egress_region now warns instead of raising. BrowsingAPI.create_context() logs a warning for an egress_region missing from the SDK's location list and still sends the request, as it does for egress_info. A non-string egress_region still raises ValidationError.

  • create_context.py and bulk_create_contexts.py default to World for research contexts. With --research and no --egress they fell back to DEFAULT_EGRESS_INFO (New York) with datacenter categories, which an org without that egress rejects. They now send World with no categories. --egress behaves as before.

  • scripts/scheduled_visual_harvest.py accepts every egress name a visual task takes. --egress was checked against cities only, so World, regions and countries were refused. --list-egress now lists World, then regions, countries and cities.

Security

  • The bundled Postman collection's saved examples no longer carry real platform identifiers. Sanitization matched on field name, so it only ever covered keys someone had thought of in advance — and object ids reached the committed collection under bucket_id, create_user_id, file_id, org_id and task_id, none of which were on that list, along with a hostname from the environment the examples were recorded against. Identifiers are now matched by the shape of the value (a 32-character hex string, wherever it appears) rather than by the key carrying it, so a field nobody predicted cannot reintroduce the problem. 202 identifiers were replaced.
  • Replacements are deterministic and one-way. A given identifier maps to the same stand-in everywhere, so a flow that threads an id from one request into the next stays coherent, and re-running sanitization is a no-op rather than a second round of rewriting. The original is not recoverable from what is published.
  • Hand-written placeholders are preserved, including the org_id and task_id values that the examples' own notes refer to by value. An earlier revision of this change preserved only runs of zeros and rewrote six placeholders into values that read like real ids; the guard now covers any repeated character, while still mapping a genuine id that merely contains a long internal run.

[0.14.2] - 2026-09-14

A correctness release for the MCP server and the async file paths. No public API changes: every method name, signature and return shape is identical to 0.14.1. What changes is behavior under concurrency — the MCP server no longer goes unresponsive for the duration of each tool call, and async downloads stop serializing behind one another's disk writes, stop opening a fresh connection per file, and stop retrying failures that cannot succeed on a retry. Two inputs that were previously accepted are now rejected outright: API_URL values carrying credentials (see Fixed), and MCP tool output paths outside MCP_FILE_ROOT (see Security).

Fixed

  • The MCP server no longer stalls while a tool runs. Every tool is a synchronous function that makes a blocking API call, and the MCP framework calls a synchronous tool directly on the event loop rather than handing it to a worker. One slow call therefore froze the whole server for its duration — nothing else could be dispatched, no progress or cancellation could be processed, and a client's own timeout could fire against a server that was merely waiting. Tool bodies now run on a worker thread, so the server stays responsive and concurrent tool calls actually overlap. No tool signature, name, or schema changes; this is invisible except that the server keeps answering.
  • Bulk async downloads reuse one HTTP connection pool instead of opening a client per file. bulk_download_async previously created a fresh HTTP client for every file, which meant a new TLS handshake per download and no keep-alive across a batch. It now shares one client across the batch. The per-file methods are unchanged for direct callers, which still get a client of their own.
  • FileAPI no longer rebuilds its TLS trust store on every download. The CA bundle is parsed once when the client is constructed, matching what HarvesterAPI already did. On a bulk download this removes one full bundle parse per file.
  • Async downloads no longer block the event loop while writing to disk. Writes were issued inline inside the coroutines — and, for chunked downloads, once per 8 KiB chunk — so concurrent downloads serialized behind each other's disk I/O. Writes are now offloaded, and chunked downloads buffer before writing rather than paying a hop per chunk.
  • The remaining filesystem calls in the async download paths are offloaded too. Creating the destination directory, and opening and closing the file in the chunked path, were left running inline once the writes had been moved off the loop. Each of those blocks exactly as a write does, so on a slow or network-mounted destination every concurrent download in a bulk run still stalled the loop for the duration of its own directory creation — the stall those downloads run concurrently to avoid. A directory that cannot be created now raises FileAPIError like every other filesystem failure in these methods, rather than a bare OSError a caller would have to catch separately.
  • A Retry-After header in date form no longer crashes a rate-limited synchronous request. RFC 7231 allows either a delay in seconds or an HTTP-date, and the date form is what most proxies and CDNs emit on a 429. The synchronous client passed the header straight to an integer conversion, so a date raised ValueError out of the response handler — a crash instead of the RateLimitError the caller was prepared for, and one that no retry logic could act on. A header that is not a plain count is now treated as absent and a default pause is used. The asynchronous paths already handled this.
  • Async download retries stop on errors that cannot succeed on a retry. The retry loop caught every HTTP failure, including responses the server had definitively rejected, so a 401, 403 or 404 was re-sent until the attempts ran out — turning one rejected request into several and delaying the identical error by the whole backoff. Transport failures, 5xx, 408 and 429 still retry; other 4xx now fail immediately with the same error they would have failed with eventually. A malformed request URL, an unsupported scheme, a redirect loop or an undecodable body are likewise no longer retried, since each reproduces exactly on the next attempt.
  • A failed async download no longer leaves a truncated file behind. download_file_with_retry_async wrote the response with a call that opens the file in truncating mode, so a write that failed partway — a full disk, a permission revoked mid-write — destroyed any existing file at that path and left the remnant in place, indistinguishable from a complete download. It now removes the partial file and reports the write failure, matching what the chunked and synchronous downloads already did.
  • Async downloads honor Retry-After on a 429. The async retry schedule was purely exponential, so a server asking for a 60-second pause was retried after one second and again after two — three requests inside the window it asked us to sit out, which is how a rate limit escalates into a longer block. The header is now respected where it is longer than the computed backoff, bounded so a bad value cannot stall a download indefinitely. The synchronous path already did this.
  • API_URL values with embedded credentials are rejected. A URL of the form https://user:password@host was accepted, and the password would then appear verbatim in request logs and in the text of any HTTP error raised against that host. This API authenticates with tokens rather than URL credentials, so there is no legitimate use for the form and it is now a configuration error.

Security

  • Two more MCP tools now confine the local paths they write to. MCP_FILE_ROOT has governed a8_upload_file and a8_download_file since 0.14.0, but a8_download_harvest_result and a8_export_logs_csv were left out, and both take a destination path from the client. Unconfined, each is an arbitrary file write driven by a path the model chose — overwriting a shell startup file or an authorized_keys with attacker-influenced content is code execution, and a8_export_logs_csv also opens its target in truncating mode and removes it if the export fails partway, making it an arbitrary delete as well. The harvest case is the worse of the two, because the bytes written are a harvest of a URL the model also chose, so both halves of the write are model-controlled. Both tools now resolve the path inside MCP_FILE_ROOT and refuse anything outside it, with .. segments and symlinks resolved before the check rather than after.
  • Action required if you passed absolute paths to either tool. A path outside the root now raises rather than writing. Point it inside the root, or set MCP_FILE_ROOT to the directory you intend the server to write to.
  • Their generated default paths moved inside the root too. With no output_path, both previously wrote directly to the system temporary directory; they now write under the configured root. A confinement that only covered caller-supplied paths would leave the default outside it. a8_download_harvest_result additionally reduces the task ID to a bare filename before using it, since it lands in the generated name.

Changed

  • Documentation corrected: the async paths use httpx, not aiohttp. The create_ssl_context docstring — which is published in the API reference — showed an aiohttp connector example that does not apply to this SDK and would not work as written. It now shows the httpx usage the SDK actually supports. aiohttp is not and has never been a dependency.
  • .env.example documents the MCP server's bind and allowlist settings. MCP_BIND_HOST and MCP_ALLOWED_HOSTS were configurable and undocumented, including the fact that binding to a non-loopback address without an allowlist makes the server refuse to start rather than run without DNS-rebinding protection. The docker-compose.mcp.yml comment describing that case had also gone stale — it still said the server merely logged a warning and carried on, which understates a control that now fails closed.

[0.14.1] - 2026-09-09

A dependency and packaging release. No SDK behavior changes: every public method, signature and return shape is identical to 0.14.0. What changed is what a fresh install is allowed to resolve to, and the fact that there is now a second name on PyPI that resolves to the MCP server.

Added

  • New silo-sdk-mcp distribution on PyPI — pip install silo-sdk-mcp now works. It contains no code. It is an alias that depends on silo-sdk[mcp-server] at an exact matching version, so it installs precisely what pip install "silo-sdk[mcp-server]" installs and nothing else. The MCP server continues to ship inside silo-sdk as the silo_sdk_mcp package and the silo-sdk-mcp console script; this is a discoverability alias, not a split.
  • Nothing changes for existing installs. silo-sdk[mcp-server] remains the primary spelling and is what you want if you already depend on the SDK. Reach for silo-sdk-mcp only if the server is what you came for and the SDK is incidental.
  • The two are pinned together with == and released from the same commit, so they cannot skew: the version of the alias is always the version of the server it installs. The console script is declared only by silo-sdk — two distributions claiming the same script name would make which one you get depend on install order.

Security

  • Every dependency lower bound has been raised past the known vulnerabilities in the versions it used to admit. A >= bound is a security statement, not only a compatibility one — the resolver may legitimately pick the floor in any environment that already pins that package, so a fresh install resolving to something current proves nothing about the range being published. Nothing here means an install of v0.14.0 was itself vulnerable: a default pip install resolved to current releases throughout, and the dependency audit that runs in CI passed against that resolution. What was wrong is what the package permitted, and only a consumer whose own environment held one of the older versions would have been affected. Each floor now sits at the first release clearing every advisory known against the range below it.
  • requests >=2.32.5 → >=2.33.0 (GHSA-gc5v-m9x4-r6x2)
  • urllib3 >=2.6.3 → >=2.7.0 (GHSA-qccp-gfcp-xxvc, GHSA-mf9v-mfxr-j63j)
  • python-dotenv >=1.0.1 → >=1.2.2 (GHSA-mf9w-mj56-hr94)
  • cryptography >=46.0.5 → >=50.0.0, in both the decrypt and legacy-decrypt extras — six advisories against the old range, the last of them fixed only in 50.0.0 (GHSA-g6cj-pr64-35w5, GHSA-jwv3-5hgf-82ww, GHSA-m2h6-j472-rp4c, GHSA-m959-cc7f-wv43, GHSA-p423-j2cm-9vmq, GHSA-537c-gmf6-5ccf)
  • mcp[cli] >=1.0.0 → >=1.28.1 in the mcp-server extra (GHSA-9h52-p55h-vw2f, GHSA-jpw9-pfvf-9f58, GHSA-vj7q-gjh5-988w) — see Fixed below, because this bound was also broken for a non-security reason.
  • Action required (only if you pin transitively): these are floors, so an environment already on current releases is unaffected and needs nothing. An environment holding a pin below one of them will now fail at resolution time with an unsatisfiable-requirement error rather than installing quietly. That is the intended outcome — raise the pin.
  • certifi >=2024.07.04 → >=2026.07.22. No advisory tracks this one, because a stale CA bundle is not a vulnerability in certifi's code — it is a trust store carrying roots it should no longer carry, which is exactly the risk a floor is supposed to keep out. The old bound admitted bundles still shipping the Baltimore CyberTrust Root, expired since 2025-05-12, and — less obviously — bundles that had re-admitted the GLOBALTRUST 2020 CA after removing it, which is only permanently absent from 2025.8.3 onward. The new floor is the first bundle with no expired roots and every distrust decision applied. It is deliberately left uncapped: an upper bound on a trust store would pin consumers to a snapshot of the web PKI, which is the failure this change exists to prevent.

Fixed

  • The mcp-server extra could not install at its own declared minimums, and its lowest supported version crashed the HTTP transport. mcp[cli]>=1.0.0 admitted releases with no mcp.server.transport_security module — added in 1.10.0 — which the server imports unconditionally to configure DNS-rebinding protection. Any such release installed cleanly and then raised ModuleNotFoundError the moment the server was started over HTTP or SSE. Separately, the extra declared fastapi>=0.111.0 alongside mcp, and their transitive Starlette requirements were disjoint (<0.38 against >=0.39), so installing the declared minimums failed outright with a resolution error. Both are corrected; uvicorn[standard] moves to >=0.31.1 because that is what the new mcp floor requires.
  • pyyaml >=6.0.0 → >=6.0.2 in the mcp-server extra. 6.0.0 and 6.0.1 publish no wheels for Python 3.12 and newer, and their source distribution fails to build against current setuptools. 6.0.2 is the first release with wheels for every supported interpreter.

Removed

  • fastapi is no longer a dependency of the mcp-server extra. It was never imported. The MCP server is built on FastMCP, which constructs its own Starlette application, and no module in the distribution has ever referenced FastAPI. Installing the extra now pulls one fewer web framework and its transitive tree. No behavior changes; if your own code imported fastapi and relied on this extra to supply it, declare it directly.

[0.14.0] - 2026-09-09

A minor bump rather than 0.13.2: the silo-mcp → silo-sdk-mcp rename below is a breaking change to a published interface.

Added

  • New LOG_EXTRACT_TIMEOUT config key (A8_LOG_EXTRACT_TIMEOUT) — a dedicated request timeout for LogExtractionAPI, separate from the SDK-wide REQUEST_TIMEOUT. It ships unset, and LogExtractionAPI falls back to 600 seconds; see the behavior note under Changed, which depends on being able to tell "unset" from "deliberately set to 600".
  • New MCP_FILE_ROOT environment variable for the MCP server — the directory (or PATH-style list of directories) that a8_upload_file and a8_download_file are allowed to read and write. Defaults to a dedicated silo_sdk_mcp_files directory under the system temporary directory, created on demand. See Security below for why local file access is now confined at all.
  • REQUEST_TIMEOUT, MAX_RETRIES, and RETRY_DELAY are now environment-templated in config/default.json, so A8_REQUEST_TIMEOUT / A8_MAX_RETRIES / A8_RETRY_DELAY take effect without editing the config file. Previously the file shipped bare literals and those variables were silently ignored. All four timeout/retry variables are now documented in .env.example.
  • scripts/create_context.py — create a single browsing context and print its launch URL. Unlike bulk_create_contexts.py, the destination URL is optional: omitting --url opens the session's default start page, which is the usual way to start an ad-hoc Silo for Research session. One of --user or --org is required.

Changed

  • Python support: minimum raised to 3.11, and 3.14 added. Python 3.10 reaches end of life on 2026-10-31 and is no longer tested or supported; requires-python is now >=3.11. Python 3.14 joins the tested matrix, which is now 3.11, 3.12, 3.13, and 3.14 — the full set of releases still receiving upstream security fixes. Raising the floor also lets the SDK rely on 3.11 language and standard-library features directly.
  • Action required (Python 3.10 users only): nothing already installed breaks — an existing 3.10 environment keeps working, and the v0.13.1 tag remains the last release that installs on 3.10. Installing this version or later on 3.10 fails cleanly at resolution time with a Requires-Python: >=3.11 error rather than installing something broken, so pin to v0.13.1 or move to Python 3.11 or newer. Note that Ubuntu 22.04 LTS ships Python 3.10 as its system interpreter — install a newer interpreter or build your virtual environment on one.
  • LogExtractionAPI now defaults to a 600-second request timeout instead of the SDK-wide 30 seconds. The backend serializes extracts behind a per-extract lock with a 600-second TTL. A client that gave up at 30s abandoned a request still running server-side while the lock stayed held, so every retry failed with PermissionDenied: log.extract already in progress until the TTL expired — turning a slow success into a ten-minute outage. The client timeout is now pinned to that lock TTL, so anything that does time out has also released its lock and the retry is clean. Only log extraction is affected; the 30-second REQUEST_TIMEOUT still governs the sub-second admin and browsing calls that dominate the SDK. Set A8_LOG_EXTRACT_TIMEOUT to override.
  • The new default raises the extraction timeout but never lowers it. Anyone who had already set REQUEST_TIMEOUT above 600 to work around the old 30-second limit keeps that larger value — a fix for slow extracts that shortened them for the people most affected by the bug would be a regression in fixer's clothing. An explicit LOG_EXTRACT_TIMEOUT still wins outright, including one below REQUEST_TIMEOUT, because that is a deliberate choice rather than an inherited default.
  • Templated numeric config values are now cast to numbers and range-checked. Environment-variable substitution always produces strings — "${A8_REQUEST_TIMEOUT:-30}" resolves to "30", not 30 — so making the timeout and retry keys templatable would otherwise have handed a string to requests and broken validate_harvester_config()'s isinstance(value, (int, float)) check with a misleading "must be a positive number". REQUEST_TIMEOUT, LOG_EXTRACT_TIMEOUT, MAX_RETRIES, RETRY_DELAY, and STATUS_CACHE_TTL are coerced after substitution and before defaults are applied, on both config-loading paths. A non-numeric value now raises ConfigurationError naming the key instead of failing later somewhere unrelated. DEFAULT_MAX_USES is deliberately excluded — no consumer reads it as a number and its string form is part of the tested contract.
  • Durations accept fractional values; counts do not. REQUEST_TIMEOUT, LOG_EXTRACT_TIMEOUT, RETRY_DELAY, and STATUS_CACHE_TTL are seconds, and requests is happy with 2.5; MAX_RETRIES is a count, so a fractional value is rejected rather than truncated. Previously the same value was accepted or rejected depending only on how it arrived — {"RETRY_DELAY": 2.5} written into a config file worked while A8_RETRY_DELAY=2.5 did not, purely because substitution turns the latter into a string.
  • Out-of-range values are rejected up front. A zero or negative REQUEST_TIMEOUT / LOG_EXTRACT_TIMEOUT fails every request before it is sent, so it is now a ConfigurationError; the counts and delays reject negatives but still allow zero, which is a legitimate way to say "no retries", "no delay", or "no caching". The checks apply to literal values in a config file as well as templated ones, and a boolean is rejected outright rather than being quietly read as 1.
  • CLI entry point and Python package renamed: silo-mcp → silo-sdk-mcp, silo_mcp → silo_sdk_mcp. The console script, the server name advertised over the MCP protocol, the server key used in client configuration files, and the importable package are now all named after the silo-sdk distribution the server ships in. The package path was the last name that did not match, and silo-mcp was ambiguous enough to be worth retiring outright.
  • Action required: update the server key and command in any MCP client configuration (.mcp.json, Claude Desktop config, .codex/config.toml). Claude Code CLI users should re-register: claude mcp remove silo-mcp --scope user then claude mcp add silo-sdk-mcp --scope user -- <command>.
  • Action required (importers and python -m users): python -m silo_mcp becomes python -m silo_sdk_mcp, and any from silo_mcp… import … becomes from silo_sdk_mcp… import …. There is no compatibility shim — the old package path is gone.
  • Action required (reinstall): re-run pip install -e ".[mcp-server]" (or reinstall the wheel). The silo-sdk-mcp console script and, for editable installs, the generated import finder both bake the module path in at install time and do not update on a git pull — until you reinstall, the console script fails with ModuleNotFoundError: No module named 'silo_mcp'. Note that python -m silo_sdk_mcp run from the repository root keeps working regardless, because the current directory is on sys.path; that masks the problem in local smoke tests, so reinstall rather than relying on it.
  • Action required (credentials file and Docker): the credentials file moves with the package, on the host as well as in the image — silo_mcp/credentials.yaml → silo_sdk_mcp/credentials.yaml, and /app/silo_mcp/credentials.yaml → /app/silo_sdk_mcp/credentials.yaml. Because that file is gitignored, pulling this change deletes the tracked files around it but leaves your credentials file behind in an orphaned silo_mcp/ directory. Move it, then delete the leftover directory — it holds live API tokens. Do this before starting Compose: a bind mount whose host path is missing gets created as an empty directory rather than failing, so the container starts and then dies parsing a directory as YAML.
  • Logging namespace changed from silo_mcp to silo_sdk_mcp. Any downstream logging configuration keyed on the old logger name silently stops matching — no error, just lost filtering or routing.
  • Tool names are unchanged — all 73 tools keep their a8_ prefix.
  • Development tooling: Ruff replaces black, isort, flake8, bandit and pylint. One tool now covers formatting, linting, import sorting, docstring style and security scanning, configured in one place ([tool.ruff] in pyproject.toml) rather than across four files that could disagree. Nothing in the shipped package changes; this affects contributors only. Details worth knowing if you have a local checkout:
  • Coverage is preserved, not traded away. Ruff's S rules are flake8-bandit — the same rule set bandit ran — and D runs under the pep257 convention flake8-docstrings defaulted to, with the same rules disabled as before. E/W/F/B/C4 cover flake8 and its usual plugins. The two jobs Ruff structurally cannot do, because it reads one file at a time, are still handled separately: mypy for type checking and pip-audit for dependency CVEs. Pylint is simply gone — it ran with --exit-zero, so it never gated anything.
  • One formatting pass touched 26 files. ruff format is a black reimplementation but not byte-identical to black 26.3.1: it rejoins implicit string concatenations that fit on one line, and spaces binary operators inside f-strings. The changes are mechanical and were made in the same commit as the tool swap.
  • Line length behaves as before. The formatter wraps at 88 and the lint gate still fails at 100, matching what flake8 enforced — a long URL or string literal the formatter cannot split does not suddenly become an error.
  • Lint and format now run over the whole tree in CI, not a path list — so the CI steps cannot drift from what the pre-commit hooks check. examples/, eval/, config/ and setup_venv.py were never gated before and came in clean, making the staged cleanup CONTRIBUTING.md had planned for them unnecessary. Two exclusions, both in [tool.ruff]: Documentation/archive/, and *.md — Ruff can format Python code blocks inside Markdown, which is a docs decision rather than a linter one.
  • Type annotations modernized to PEP 585/604 — Dict[str, Any] is now dict[str, Any], Optional[X] is X | None, and the typing imports they needed are gone. Ruff's UP rules flagged ~1,900 of these once the floor moved to 3.11; the rewrite is mechanical and lands in its own commit so the churn does not obscure the tool swap. The package ships py.typed, so this is visible to consumers reading the annotations — but only as spelling, since both forms mean the same thing to a type checker and 3.11 is already the minimum.
  • Action required (contributors): re-run pip install -e ".[dev]" and pre-commit install --install-hooks. black, isort, flake8, bandit and pylint are no longer dev dependencies, and .flake8 has been deleted.
  • OrgManagementAPI.delete_org() now raises instead of returning False. The method advertised True on success and False on failure, but False was unreachable: the server answers a delete with either a confirmation payload or an error, and an error already raised OrgManagementAPIError. The False branch could only be reached by a response shape the API does not produce, so in practice the method already either returned True or raised — while its signature invited callers to write if not api.delete_org(name): and handle a case that never arrives, and to not handle the exception that does. An unconfirmed response is now an OrgManagementAPIError naming the org and the result it got, rather than a log warning and a falsy return that is indistinguishable from a genuine refusal.
  • Action required (callers that branch on the return value): wrap the call in try / except OrgManagementAPIError instead of testing the result. Code that only checks truthiness keeps working unchanged, because the success return is still True. Code that treated False as "deletion failed" was never reached and was silently reporting nothing; the exception now carries the server's own refusal message — most often that the organization still contains users or sub-orgs.
  • The docstring also described a permanent hard delete. The server soft-deletes: it stamps an expiration on the organization and queues its removal. The organization is immediately unusable and there is no API to reverse it, so the practical effect is unchanged, but the previous wording described mechanics that are not what happens. The a8_delete_org MCP tool description carried the same two errors and has been corrected to match.
  • dev now carries a .dev0 version suffix while it is ahead of the last tag. Until now dev reported the same __version__ as the release it branched from, so a pip install -e from a dev checkout was indistinguishable from the tagged release despite differing behavior — which made "which SDK produced this result?" unanswerable during a support investigation. dev will be set to <next>.dev0 immediately after each release and to the bare version at tag time.

Security

  • The MCP file tools now confine local filesystem access to a configured root. a8_upload_file took any local path and sent its contents to the storage API; a8_download_file took any local path and wrote bytes to it. Both paths come from the model, and this SDK exists to fetch web content and hand it to that model — so in the ordinary use case the path is influenced by pages the operator does not control. Text on a fetched page that talks the model into a8_upload_file("/proc/self/environ") exfiltrates every A8_* token the server process holds, and a download aimed at ~/.ssh/authorized_keys or a shell rc file is a straight path to code execution on the host. Neither tool checked anything.
  • Both tools now resolve the requested path (following symlinks, so a link inside the root cannot smuggle one out) and reject anything that does not land inside a permitted root. A relative path anchors to the first root rather than to the server's working directory, which the client cannot see and which typically holds .env.
  • The default root is a dedicated silo_sdk_mcp_files directory under the system temporary directory, created on demand. It is deliberately not the working directory and not the whole temp directory. Set MCP_FILE_ROOT to point somewhere real; it accepts a PATH-style list, so a read directory and a write directory can both be permitted without widening either.
  • Action required (existing MCP deployments): an upload or download naming a path outside the root now fails with a message saying which roots are permitted. If your workflow moves files through a specific directory, set MCP_FILE_ROOT to it before upgrading.
  • The MCP HTTP transports now refuse to start when DNS-rebinding protection would be off. Binding to a non-loopback host without MCP_ALLOWED_HOSTS previously logged a warning and started anyway, with host-header validation disabled — the configuration where any web page the operator visits can drive the server through the browser. The warning was the only thing standing between a copy-pasted --host 0.0.0.0 and an unauthenticated local attacker, and warnings scroll past. The server now exits with a non-zero status and an explanation. An explicitly empty MCP_ALLOWED_HOSTS is treated the same way, rather than as "allow everything".
  • --credentials pointing at a directory or an empty file now exits instead of starting. A bind mount whose host path does not exist is created as an empty directory, so this was the failure mode of a mistyped Compose path: the server started, parsed nothing, and served no credentials while reporting itself healthy.
  • Response bodies are now actually redacted before being logged. _redact_response matched a single key name that only ever appears in requests, so on a response it was a no-op — every unexpected-shape error logged the server's reply verbatim, and API replies carry session identifiers and, on some paths, tokens. It now walks nested dictionaries and lists and masks values under any key containing token, password, secret, api_key, credential, private_key, session_id or authorization, and the rendered form is truncated so a large reply cannot flood the log. This was a control that existed in name only; the name is now accurate.
  • API_URL must use HTTPS. Nothing checked the scheme, so an http:// value — from a typo, a copied internal note, or an attacker-writable config file — silently sent every API token in cleartext. A non-HTTPS API_URL is now a ConfigurationError at client construction. Loopback addresses (127.0.0.1, localhost, ::1) are still allowed over HTTP, with a warning, because that is how local mock servers are used in testing.
  • Removed the VERIFY_SSL config key. It appeared in config/default.json, config/production.json and the configuration reference, but no SDK code read it — certificate verification is unconditional on both the synchronous and the aiohttp paths, against the certifi trust store. A documented switch that does nothing is worse than no switch: it invites someone to set it to false, conclude verification is off, and design around that. It has been deleted rather than wired up, and the configuration reference now states plainly that verification is not configurable.
  • scripts/setup_a8_api_env.sh writes to .env, not ~/.zprofile. It prompted for five API tokens and appended them to the user's login profile, which exports them into the environment of every process that user starts — where they leak through /proc, crash dumps and diagnostics — and which is created world-readable. It now writes the repository's gitignored .env at mode 0600, via an atomic replace so an interrupted run cannot truncate a file full of credentials. Existing export A8_* lines are recognized and replaced rather than duplicated. Tokens already sitting in a ~/.zprofile from an earlier run should be removed by hand and rotated.
  • scripts/run_postman_eval.sh no longer passes tokens on the command line. Every account on the host can read the full argv of a running process out of ps, and CI runners log the command they invoked. The five tokens now travel in a short-lived 0600 environment file inside a randomly-named temporary directory, removed on exit.
  • Scrubbed captured production values from the Postman collection and .env.example. A saved example response in the collection carried a real production hostname along with live-looking organization, bucket and task identifiers, and .env.example carried a real Microsoft Entra tenant and application ID. All are now placeholders. The internal script that regenerates those examples reads its SAML metadata URL from the environment instead of a hardcoded tenant URL.
  • .dockerignore excludes the per-environment config files. config/qa.json, config/eng.json and config/demo.json are gitignored, so unlike default.json and production.json nobody reviews what a developer put in them. A local copy holding real tokens would otherwise be copied into the build context and baked into a layer that cannot be rotated.
  • Test files are no longer exempt from the TLS lint rules. The bandit configuration Ruff replaced excluded the whole test tree, and carrying that over wholesale also switched off S501 (a request with certificate verification disabled) and S323 (an unverified SSL context) — the two rules that catch a "just for the test" TLS bypass, which is exactly where one gets written. The per-file exemption is now an enumerated list of the rules that genuinely are noise in a test suite (asserts, fake tokens, temp paths), and the TLS rules gate the tests like everything else.
  • seccure is now upper-bounded (>=0.5.0,<1.0) in the optional legacy-decrypt extra, matching every other dependency. It has had one release since 2014, so a surprise 1.0 would most likely be a new maintainer or a name transfer rather than an upgrade — not something an unbounded >= on a crypto package should resolve to silently.
  • Docker images no longer bake in the local credentials file. Dockerfile.mcp copies the whole working tree, and .dockerignore carried no entry for silo_sdk_mcp/credentials.yaml — so on any machine where the server had been run locally, docker build copied live API tokens into an image layer. .gitignore does not apply to Docker builds. The server reads its credentials from a read-only bind mount at runtime, so the file has no reason to be inside the image at all; it is now excluded by basename, so the exclusion holds regardless of where the package sits. Editor and agent working directories and local scratch output were being copied in as well, and are now excluded too — that alone takes the image from 1.33 GB to 796 MB. The same exclusions were added to MANIFEST.in, since an sdist is likewise built from the working tree rather than from git.
  • Action required: rebuild any image built before this change. An image layer cannot be scrubbed after the fact, so if such an image was pushed to a registry or otherwise shared, treat the tokens in it as exposed and rotate them.

Fixed

  • The log-extraction timeout clamp never ran. The guarantee described under Changed — that the new 600-second default raises an existing larger REQUEST_TIMEOUT but never lowers it — was keyed on LOG_EXTRACT_TIMEOUT being absent from the configuration. But config/default.json shipped "${A8_LOG_EXTRACT_TIMEOUT:-600}", which resolves to 600 whether or not the environment variable is set, so the key was always present and always looked deliberate. Anyone who had raised REQUEST_TIMEOUT above 600 to work around the old 30-second limit silently had their extraction timeout cut to 600 by the release that was supposed to protect it. The shipped default is now empty, and a blank value is treated as unset — so the clamp works, and an explicit 600 is once again distinguishable from no setting at all.
  • A blank templated numeric config value is now treated as unset rather than as an error. "${A8_LOG_EXTRACT_TIMEOUT:-}" with the variable unset resolves to an empty string, which the numeric coercion rejected with LOG_EXTRACT_TIMEOUT must be a number, got ''. Because every CLI script under scripts/ loads the configuration at import time, that turned --help into a traceback on a machine with no A8_* variables exported. Blank values for any of the numeric keys are now dropped, so consumers see a missing key and apply their own default.
  • walk_org_tree() and print_org_tree() no longer skip subtrees silently. Both swallowed every exception while descending, so an organization the caller lacks rights on — or a transient API error — produced a quietly truncated tree that looks exactly like a complete one. Skipping the branch is still the right behavior, since one inaccessible organization should not abort a whole-tree walk, but it now logs a warning naming the branch and the reason, so a short answer is visibly short. (The previous code carried a # nosec marker, which has been inert since bandit was replaced by Ruff's S rules — Ruff reads noqa.)
  • scripts/run_postman_eval.sh ignored A8_CONFIG_ENV and always ran against production. The variable was documented in the script's own usage text, but the Production environment file was hardcoded — so A8_CONFIG_ENV=eng ./scripts/run_postman_eval.sh ran the full collection, creates and deletes included, against production while reporting otherwise. The variable now selects between the production, engineering and QA environment files, and an unrecognized value is an error rather than a silent fall-through. The default is also now eng rather than prod: a run that creates and deletes real users and orgs should not target production because someone forgot to set a variable.
  • The 100-character line-length gate was never enforced. E501 was listed in Ruff's ignore, and ignore takes precedence over select — so the max-line-length = 100 setting alongside it, and the changelog note in this release saying the lint gate still fails at 100, described a check that could not fire. E501 has been removed from the ignore list; the tree already complied.
  • The MCP credentials template was missing from installed packages. Neither the wheel nor the sdist contained silo_sdk_mcp/credentials.yaml.example or silo_sdk_mcp/README.md, so the documented setup step of copying the template out of the installed package only ever worked from a git clone. Both files now ship, listed explicitly as package data rather than relying on MANIFEST.in to reach the wheel.
  • Dockerfile.mcp installed the package before copying the source into the image. An editable install resolves its package list at install time, so installing against a directory holding only pyproject.toml produced an import finder with an empty mapping, and the later source copy could not retroactively fix it. Inside the image the silo-sdk-mcp console script failed with ModuleNotFoundError and imports only worked from /app. This was masked by the container's own CMD, which uses python -m and therefore picks the package up from the working directory regardless. The source is now copied before the install.
  • Numeric values in credentials.yaml were not cast on the MCP HTTP-transport path. The per-client configuration loader ran environment-variable substitution but not the numeric coercion the SDK's own config loader applies, so a credentials.yaml written in the documented "${A8_REQUEST_TIMEOUT:-30}" style handed requests the string "30" and every call from an HTTP-transport client failed with a TypeError from inside the HTTP layer. Both loading paths now share one coercion step, so they cannot drift apart again.
  • silo-sdk-mcp --credentials defaulted to a path relative to the current directory. The default was silo_sdk_mcp/credentials.yaml, resolved against wherever the shell happened to be — but the setup instructions have users copy the template out of the installed package, so the file they end up editing sits next to the module. Starting the server from anywhere other than a repository root therefore failed to find a credentials file that was exactly where the docs said to put it. The default is now derived from the package location, which resolves to the same path as before in both documented layouts (a checkout run from its root, and /app in the image).
  • The Compose file's MCP_ALLOWED_HOSTS default ignored MCP_BIND_HOST. Binding the container to a non-loopback address left the DNS-rebinding allow-list pinned to 127.0.0.1:8080, so every request to the address the server was actually reachable on was rejected — with a host-header error that gives no hint the bind address is involved. The default now derives from MCP_BIND_HOST, and an explicit MCP_ALLOWED_HOSTS still overrides it.
  • The remote-deployment documentation described the superseded SSE transport as the default. The setup and overview pages showed --transport sse, the /sse endpoint in every reverse-proxy example, and an MCP_CREDENTIALS_FILE environment variable the server does not read; the published port example also bound 0.0.0.0. They now document streamable-http and its /mcp endpoint, bind the published port to loopback so a reverse proxy is the only route in, and note where MCP_ALLOWED_HOSTS must list the public hostname. sse still works and is still documented as the fallback for older clients.
  • The same correction reached the packaged silo_sdk_mcp/README.md and the CLI's own --help text, which still described --port and --credentials as SSE-only and showed a /sse client URL. A reader who took the transport advice from the published docs and the endpoint from the bundled README would have configured a client that could not connect. The security note now also states that --host defaults to 0.0.0.0 — every interface — and points at --host 127.0.0.1 behind a TLS-terminating proxy.
  • The configuration reference omitted seven shipped config keys. TOP_ORG appeared only as a script-scoped environment variable despite being required by a8_validate_config and probed by a8_health_check, and ENABLE_STATUS_CACHE, STATUS_CACHE_TTL, RATE_LIMIT, DEFAULT_EGRESS_INFO, DEFAULT_POLICY and ENABLE_REQUEST_LOGGING were absent entirely — all six ship in config/default.json, so readers met them for the first time in a file the docs never explained. The A8_REQUEST_TIMEOUT / A8_MAX_RETRIES / A8_RETRY_DELAY mappings were missing from the environment-variable table as well. All are now documented, along with a note that ORG_VANITY_URL is not the API org name — TOP_ORG is. Two are documented as inert rather than as working settings: nothing reads ENABLE_REQUEST_LOGGING, and RATE_LIMIT is shape-validated but never enforced, so the SDK does not throttle on your behalf.
  • The remote-deployment documentation showed a two-client credentials.yaml that will not start. It described the server as loading the first client entry and sharing those credentials across all authenticated sessions; in fact the server counts the entries and exits rather than serve one client's tokens to another. Anyone following the example got an immediate startup failure with no hint that the file itself was the problem. The example is now single-client, and the architecture diagram shows one instance per client behind the proxy — which was always the supported shape for serving more than one.

Removed

  • silo_sdk_mcp.__version__ and config.__version__. Both were sub-package version numbers with no consumers, and both had silently drifted from the distribution version (the MCP sub-package, then named silo_mcp, sat at 0.10.3 through four releases; config at 0.8.2 since April). silo_sdk.__version__ is the single source of truth — as DEFAULT_USER_AGENT already assumes. A second number that can drift is worse than no number.

[0.13.1] - 2026-07-17

Changed

  • Raised MCP tool test coverage from 95% to 100% by adding tests for previously-untested error-handling and edge-case branches across every silo_mcp/tools/* module.
  • raise_mcp_error(), the shared exception-translation helper used by all MCP tools, is now type-annotated as never returning normally, and the defensive raise statements that used to follow it (which could never execute) have been removed.
  • Fixed a misleading comment on the log-extraction retry loop's exhaustion guard: passing a negative max_retries to a8_extract_logs skips the extraction attempt entirely and raises a generic "Exhausted retries" error rather than being unreachable as previously documented; this is now covered by a test and documented accurately in the code.

[0.13.0] - 2026-07-15

Security

  • SAML metadata parsing hardened against SSRF and XML entity-expansion attacks — found in a security review of parse_saml_metadata() / fetch_metadata_url() (used by a8_parse_saml_metadata and the SSO-import CLI command):
  • fetch_metadata_url() now only accepts http/https URLs and rejects loopback, private, link-local, multicast, unspecified, and reserved IPv4/IPv6 destinations. Every DNS answer and redirect target is validated before a request is sent; requests are pinned to a validated address and the connected peer is checked to prevent DNS rebinding. Non-http(s) schemes still raise a clear ValueError before any fetch is attempted.
  • MCP downloads that omit output_path now sanitize the storage-provided filename and place it inside a uniquely-created temporary directory, preventing absolute paths or traversal segments from escaping the temporary download location.
  • parse_saml_metadata() now parses XML with defusedxml instead of the standard library parser, which rejects entity-expansion ("billion laughs") payloads and external entity references (XXE) up front instead of resolving them. defusedxml is now a required dependency.
  • parse_saml_metadata() no longer silently uses the first EntityDescriptor when given a metadata bundle containing more than one (e.g. a federation aggregate). It now raises a clear error asking the caller to disambiguate, unless the new optional entity_id parameter is supplied to select which entity to use.
  • Breaking change: tampered or corrupted encrypted log entries were silently returned as if successfully decrypted. decrypt_log_entry() caught every decryption error — including AES-GCM InvalidTag, the exact signal that a ciphertext was tampered with or corrupted — and returned a dict with just an error field merged into the entry's normal wrapper fields (create_ts, seq_id, ...). That result was indistinguishable from a genuinely decrypted row to any caller that didn't inspect every entry for an error key, and decrypt_logs() appended it straight into the "successfully decrypted" list. Decryption/authentication failures are no longer swallowed:
  • decrypt_log_entry() now raises the new LogDecryptionError on any decryption or authentication failure instead of returning a pseudo-success dict.
  • decrypt_logs() raises the same error by default as soon as a failing entry is encountered (stopping the batch, so partial results are never silently mixed with tampered data). Pass the new track_failed=True to instead collect failed entries into a separate list and keep processing the rest of the batch — mirroring the existing track_missing parameter for entries with no matching key.
  • Failed entries are never merged into, or returned alongside, successfully decrypted entries.
  • Callers that previously checked decrypted entries for an error key should instead catch LogDecryptionError (or pass track_failed=True and inspect the returned failed-entries list).
  • standard_decrypt_chunked() could leave unauthenticated plaintext in the output stream after a failed decryption. AES-GCM only validates the authentication tag inside finalize(), which runs after plaintext chunks have already been written via update() — contrary to the function's own docstring, which incorrectly claimed output was "buffered internally and written only after the auth tag is validated." On authentication failure, the function now makes a best-effort attempt to truncate any unauthenticated bytes back out of the output stream, and the docstring has been corrected to describe the real behavior and the temp-file-and-move-on-success pattern callers writing to a persistent destination should use. decrypt_video_file() now removes its plaintext temporary file after every failed decrypt, write, or final move.
  • CSV log export had no formula-injection sanitization. Untrusted log field values (URLs, POST data, clipboard contents, query strings, domains, ...) starting with =, +, -, @, a tab, or a carriage return could execute as a spreadsheet formula (e.g. =HYPERLINK(...), =IMPORTXML(...)) when the exported CSV is opened in Excel or Google Sheets, per the OWASP CSV Injection advisory. LogExtractionAPI.export_logs_to_file(format_type="csv") now prefixes any such value with a single quote so spreadsheet applications render it as literal text.

Fixed

  • Key store round trip was broken. add_key_to_store() base64-encodes PEM text before writing it to the pvtkey.txt store (necessary since a multi-line PEM value can't be represented on the store's single name=value line), but load_private_keys() never decoded it back — so the documented generate_key_pair() → add_key_to_store() → load_private_keys() → decrypt workflow hard-failed with a ValueError inside load_pem_private_key(). load_private_keys() now automatically detects and decodes base64-encoded PEM values written by add_key_to_store(); Legacy passphrases, .pem file paths, and hand-written raw PEM values are left untouched.
  • ENC log schema listed the wrong field name. The ENC CSV schema in log_schemas.py listed enc_algorithm, but the Authentic8 API documentation's Extract Log response example confirms the actual field returned alongside encrypted log entries is encryption_type (e.g. "encryption_type": "Legacy"). With the wrong name, CSV export (extrasaction="ignore") silently dropped the field, and a later CSV-to-decrypt run would default every entry to Legacy regardless of its actual encryption type. Corrected to encryption_type.
  • HTTP retries could re-execute non-idempotent requests. The shared Retry adapter allowed POST on 429/500/502/503/504, so a transient error after the server had already applied a mutating command (e.g. adduser, reset_pin) could cause the client to retry it, risking a duplicate side effect. allowed_methods is now restricted to idempotent verbs only (GET, HEAD, PUT, DELETE, OPTIONS).
  • batch_request returned the injected setauth acknowledgment as a false successful result. The ack (always index 0) was only stripped when the response had more than one element, so a single-command batch whose response contained only the ack — e.g. a command rejected at the auth phase — returned that ack disguised as the command's result. The ack is now stripped unconditionally. batch_delete_users also now applies the same "user not found" soft-success translation delete_user() already had, so the batch and single delete paths present a consistent result contract.
  • modify_file posted directly to the base URL, missing the api/ path segment, instead of routing through the shared request helper like every other command. upload_file/download_file bypassed the shared HTTP session entirely (via bare requests.post), skipping session-level retry/proxy/User-Agent configuration. get_file_info performed a full-bucket findfiles scan and filtered client-side instead of a targeted, file_id-scoped lookup. All three now use the shared request path/session. A failed upload or download (sync and chunked-async) also no longer leaves a truncated partial file behind — the partial file is now cleaned up on error.
  • Config loading did not treat a present-but-empty environment variable as unset. ${VAR:-default}-style substitution only fell back to the default when a variable was entirely absent, so an explicitly empty A8_* value (e.g. A8_API_URL="") resolved to an empty string instead of the documented bash-style fallback, breaking every request with a blank base URL. config/production.json's fallback API_URL also embedded a redundant /api/ (producing a double /api/ and 404s), and ConfigBuilder bypassed .env file loading entirely, unlike load_config(). A shell/process-level A8_CONFIG_ENV now also reliably takes precedence over a conflicting value merely defined in .env.
  • Bulk async harvest raised KeyError on a per-task url key and ignored each task's own egress_info in favor of the bulk-level default, making it impossible to mix asset tasks (which require a datacenter location) with non-asset tasks in one call. Both url and urls per-task keys are now accepted, and per-task egress_info is honored. The async and sync harvest methods' return shapes were also unified, and egress validation now rejects connectivity+protocol combinations no single city actually supports together (e.g. isp + tor) instead of validating each dimension independently.
  • create_context's inner URL-parsing ValidationError was caught by its own generic exception handler and double-wrapped, producing a confusing "Failed to parse URL: Invalid URL format: ..." message instead of the clean one.
  • MCP a8_health_check reported stale tool-capability counts (drifted from the actual registered tool list) and always reported 0 latency on not-found/error probes instead of real elapsed time. a8_debug_payload's docstring example showed the wrong endpoint (/cmd/ instead of /api/). a8_create_org's already-exists fallback looked up the existing org by bare name, which can resolve to the wrong org if the name collides elsewhere in the hierarchy — it now scopes the lookup to the full parent path when known. The destructive a8_delete_org/a8_delete_partner_sso_config tools now reject a blank/whitespace-only org_name before making any network call.
  • Usage-report functions silently zeroed or dropped rows when a per-org/per-user session-report fetch failed, making a fetch failure indistinguishable from confirmed zero activity. Failures are now logged at WARNING (matching the existing org-traversal contract) and the affected row is marked partial: True instead — a partial row is never filtered out by include_inactive=False, so a fetch failure can no longer masquerade as a genuinely idle user. OrgManagementAPI.get_session_report() also now strictly validates the documented MM-DD-YYYY date format (previously a loose length/dash-count check silently accepted ISO YYYY-MM-DD dates and non-zero-padded values).
  • Two of the SDK's seven independent org-tree traversal implementations had no cycle guard at all (get_org_usage_report, OrgManagementAPI.get_org_tree), unlike their siblings — a malformed or cyclic get_org_children response could produce duplicate rows. All org-tree traversals (list_users_recursive, get_org_usage_report, get_user_usage_report, get_org_tree, and the move_users.py/find_user_orgs.py scripts) now share a single, consistently cycle-guarded and deduplicated traversal implementation.
  • a8_list_users_recursive was missing its own parameter-validation error handling, so an invalid max_depth surfaced as a generic "API request failed" error instead of a clear "Invalid parameters" message.

Changed

  • MCP tool error messages are more specific and actionable. All MCP tool functions now route SDK exceptions through a shared error-translation helper instead of each hand-rolling its own conversion — rate-limit, authentication, and not-found errors get specific, actionable hints (e.g. "Use a8_find_user to search by partial email or name") instead of a generic "API request failed" message. Exception types raised to callers (ValueError/RuntimeError) are unchanged.
  • modify_user/list_users now raise on an unexpected API response shape instead of silently returning a sentinel value ({"status": "unknown", ...} / []), so a broken or reshaped response is no longer indistinguishable from a genuinely empty result.

[0.12.0] - 2026-07-15

Fixed

  • Org-name collision could silently drop or misattribute data — a bare org name is not guaranteed unique within a hierarchy (the same leaf name, e.g. "Research", can recur under many unrelated parents), and the platform rejects a bare name that collides elsewhere as ambiguous. This affected several SDK code paths, each now fixed to track and use the full path (e.g. "MyOrg/SubOrg") instead of the bare name:
  • list_users_recursive() / get_user_usage_report() (MCP: a8_list_users_recursive / a8_user_usage_report) — previously deduped visited sub-orgs by bare name (silently dropping a colliding org's entire subtree during traversal), and separately fetched each org's users by bare name (failing the fetch for a colliding org even once traversal found it correctly). Both issues are fixed; the org/org_name field on returned rows is now the full path for any sub-org.
  • get_org_usage_report() — fetched each org's info by bare name; now uses the full path. The org_name field on returned rows is now the full path for any sub-org.
  • OrgManagementAPI.get_org_tree() / a8_get_org_tree() — fetched each node's org_id/user count by bare name; now uses the full path internally (the nested tree's own org_name field stays bare, since nesting already gives callers path context).
  • silo_sdk.utils.org.walk_org_tree() — deduped visited orgs by bare name and fetched children by bare name; now tracks full paths (dedup is now cycle-safe via ancestor-chain checking rather than a global visited set, so it also tolerates a malformed/self-referencing API response without dropping unrelated same-named orgs). Yielded records' org_name is now the full path for any non-root org.
  • scripts/move_users.py / scripts/find_user_orgs.py — built their own org tree with no deduplication at all and searched/listed users by bare name; both now track full paths with deduplication.
  • Silent partial results on sub-org lookup failure — a failed org-children lookup while traversing a hierarchy in list_users_recursive()/get_user_usage_report()/get_org_usage_report() previously logged only at DEBUG level, giving no signal that the returned data was incomplete. These failures are now logged at WARNING, and affected functions' docstrings now document that results can be incomplete without raising an exception. A related regression from this same fix cycle — narrowing exception handling enough that a malformed (non-get_org_children) failure while processing one subtree could crash the entire call instead of degrading just that subtree — is also fixed.
  • a8_get_org_children(recursive=True) dropped org_id — the flattening step only copied org_name/current_users/depth from each tree node, silently omitting the org_id field get_org_tree() provides. Now included.

Added

  • org_id on every get_org_tree() node — a8_get_org_tree()/OrgManagementAPI.get_org_tree() now include a stable org_id per node, in addition to org_name and current_users. org_id is unaffected by bare-name collisions between orgs elsewhere in the tree.

[0.11.0] - 2026-07-09

Fixed

  • Corrected egress location connectivity data based on updated provisioning information — several locations' recorded connectivity types (datacenter/ISP/fixed-wireless/wireless-carrier) were out of date.
  • create_context (browsing) now validates the categories parameter's structure and values; previously invalid categories were silently accepted and forwarded to the API.

Changed

  • Retired the Lebanon egress location — no longer accepted as a valid egress_region/egress_info.name value.
  • Removed the EGRESS_LOCATIONS module-level constant from silo_sdk and silo_sdk.browsing. Use BrowsingAPI.get_egress_locations() instead, which returns the same data and stays current as locations change.

Added

  • Connectivity and protocol (direct/tor) selections are now validated against what is actually available at the requested egress location, for both browsing contexts and harvest tasks (video/single/visual task types). Asset harvest tasks are unaffected — they keep their existing fixed 6-location validation.

[0.10.3] - 2026-06-09

Fixed

  • Corrected the ad-blocking policy type name to ad_block with enable/disable values (previously documented as adblock with block/allow, which the API rejects).
  • Corrected the domain blocklist policy type name to domain_block (previously domain_deny) across SDK docstrings, MCP tool help, and the browsing reference docs.
  • The default User-Agent header now always reflects the installed package version. It is derived from a single source (silo_sdk.__version__) instead of being hardcoded in multiple files, where it had drifted out of date (some paths reported silo-sdk/0.10.0).

Changed

  • Clarified the browser_chrome: seamless constraint: it applies to non-catchall users. Catchall users are always shown the minimal ribbon, regardless of policy. (Previously framed as "authenticated users only.")

Added

  • Documented the optional browser_profile fields timezone (IANA name) and languages (Accept-Language string), in addition to os and browser.

[0.10.2] - 2026-05-07

Added

  • Setup script (setup_venv.py --dev) now verifies mcp and silo_mcp imports after install and prints a hint if the [mcp-server] extra is missing.

Security

  • MCP server (SSE and streamable-HTTP transports) now enforces single-client-per-process configuration with Bearer token authentication: the server refuses to start if silo_mcp/credentials.yaml lists more than one client. Every request is validated against the configured Bearer token using a constant-time comparison; a missing, malformed, or mismatched token gets HTTP 401.

Fixed

  • pyproject.toml dependency pins corrected for mcp and fastapi extras.

[0.10.1] - 2026-05-05

Changed

  • Package rename: mcp_server → silo_mcp — the MCP server package is now silo_mcp/. The CLI entry point is silo-mcp (was authentic8-mcp). Install with pip install "silo-sdk[mcp-server]".
  • Packaging fixes: wheel now correctly includes silo_mcp/ and all sub-packages.

Fixed

  • Replaced aiohttp with httpx for async HTTP to resolve a dependency conflict.
  • Windows compatibility fix for cleanup.py and test path handling.

[0.10.0] - 2026-05-05

Added

  • Egress location details — get_egress_locations(include_details=True) returns enriched per-city metadata including connectivity, availability, and protocol instead of plain name strings. Backward-compatible: default remains include_details=False.
  • EGRESS_LOCATION_DETAILS — new static dict in silo_sdk/browsing/isolation_api.py mapping all 50 egress cities to their supported connectivity types, availability modes, and protocol options. Confirmed against Harvester API docs (April 2026) and live API testing.
  • MCP a8_list_egress_locations — now accepts include_details: bool = True (enriched output by default for LLM callers). Existing callers using include_details=False get the prior flat-string behavior.
  • TOR protocol per location — protocol field populated for all cities: Sydney (["direct", "tor"]), Moncks Corner SC (["tor"] only), all others (["direct"]). Confirmed via live API testing.

Fixed

  • Availability values corrected — VALID_AVAILABILITY_TYPES in egress_validation.py changed from {"private", "shared"} to {"private", "public"} per the Harvester API documentation (April 2026, p.4). "shared" was never a valid backend value; any caller passing availability="shared" would have silently received no egress results from the backend. EGRESS_LOCATION_DETAILS, Categories TypedDict, MCP docstrings, and all tests updated to use "public".
  • TOR egress city correction — Sydney supports both "direct" and "tor" protocols; Moncks Corner SC supports "tor" only (not "direct"). Prior documentation stated both cities supported both protocols.
  • protocol field not exposed — get_egress_locations(include_details=True) previously extracted connectivity and availability from EGRESS_LOCATION_DETAILS but silently dropped protocol. All three fields are now returned.

Changed

  • a8_list_egress_locations MCP tool default changed from returning flat strings to returning enriched dicts (include_details=True). Callers that need flat strings must now pass include_details=False explicitly.

[0.9.1] - 2026-04-29

Added

  • MCP server expanded from 59 to 73 tools across 9 modules
  • Centralized error enrichment (silo_mcp/errors.py) with actionable lookup hints and automatic rate-limit retry
  • Diagnostic tools: a8_validate_config, a8_get_api_info, a8_debug_payload; enhanced a8_health_check with per-token latency and capabilities
  • Compound workflow tools: a8_harvest_url, a8_create_browsing_url, a8_org_summary, a8_stream_logs, a8_export_logs_csv
  • Resilience: fallback_per_type in a8_extract_logs, idempotency hints in a8_add_user/a8_create_org, optional bucket_id in a8_upload_file
  • Input sanitization via strip_str() applied to all MCP tool string parameters
  • Mermaid diagram support in MkDocs; replaced ASCII architecture diagrams in MCP docs
  • Docker credential delivery documentation: three methods (--env-file, -e flags, volume mount)

[0.9.0] - 2026-04-29

Added

  • Schema validation script — scripts/validate_log_schemas.py validates LOG_TYPE_FIELDS against real extracted log data; reports extra fields, empty types, and coverage summary; exit code 1 when gaps found (CI-friendly)
  • Encrypted log example — examples/decrypt_logs.py demonstrates the full ENC log extract-then-decrypt workflow with per-type breakdown and optional JSON output
  • Private key template — examples/pvtkey.txt.example documents the pvtkey.txt format for both Legacy (seccure passphrase) and Standard (ECIES/EC PEM) key types
  • Test coverage — 137 new unit tests across 4 test files:
  • tests/test_extract_all_script.py (16 tests) — extract-all script retry logic and CLI
  • tests/test_log_stats.py (66 tests) — all 11 analysis functions, formatters, and file loading
  • tests/test_mcp_logging_tools.py (27 tests) — MCP retry-on-lock behavior and exception handling
  • tests/test_export_logs_csv.py (28 tests) — CSV enhancement flags and resume state
  • Log parsing utilities — New silo_sdk/logging/log_utils.py module with JSON field parsing (parse_json_field, parse_all_json_fields), header extraction (extract_user_agents, extract_content_types), egress hierarchy parsing (parse_egress_hierarchy), type normalization (normalize_log_type, normalize_log_types), and CSV flattening helpers (expand_json_fields, flatten_nested_dicts)
  • Multi-type extraction script — scripts/extract_all_logs.py extracts multiple log types sequentially with configurable pauses and automatic retry on backend lock contention
  • Log analytics script — scripts/log_stats.py with 11 built-in analyses (domains, auth, users, egress, transfers, harvest, apps, nexus, sessions, bypasses, user_agents) and table/json/csv output formats
  • MCP retry-on-lock — a8_extract_logs gains retry_on_lock, retry_delay, and max_retries parameters for automatic lock contention handling
  • CSV export enhancements — scripts/export_logs.py gains --expand-json, --expand-nested, and --parse-egress flags for richer CSV output with dot-notation column expansion
  • NEXUS log type — Added NEXUS to VALID_LOG_TYPES and LOG_TYPE_FIELDS for Nexus AI conversation events (fields: conversation_id, message_type, org_name, toolbox_name, etc.)
  • ENC wrapper schema — Added ENC to LOG_TYPE_FIELDS with wrapper fields (create_ts, enc, enc_algorithm, key_name, org_id, seq_id, session_id, type)
  • DVR session recording how-to — New documentation page (docs/how-to/dvr-recordings.md) explaining DVR recording discovery, download, and decryption workflow via FileAPI
  • 2 new MCP tools (59 total, up from 55):
  • a8_org_usage_report (Organization Management) — Usage report across an org hierarchy showing provisioned users, active users, session counts, total/avg/longest/shortest session times per org. Params: org_name, start_date, end_date, max_depth (default 5), active_only (default False).
  • a8_user_usage_report (Organization Management) — Per-user usage report across an org hierarchy. Params: org_name, start_date, end_date, max_depth (default 5), include_suspended (default True), active_only (default False). Returns flat list with org, username, session count, total/avg/longest/shortest session times.
  • 2 new CLI scripts:
  • scripts/org_usage_report.py — Generate org-level session usage reports with tree-style hierarchy display, CSV export, and active-only filtering
  • scripts/user_usage_report.py — Generate per-user session usage reports with CSV export and filtering options
  • Management utility functions in silo_sdk/utils/management_utils.py:
  • get_org_usage_report() — Collect session statistics across an org hierarchy
  • get_user_usage_report() — Collect per-user session statistics across an org hierarchy

Changed

  • Log type field schemas synced with logtype_headers.ini v1.0.4 — Updated 13 log type schemas with new fields: A8SS (+6), ADMIN_AUDIT (+3), CASE_MANAGER (+5), EVENT (+1), EXPLOIT (+6), HARVEST (+1), ISOLATE_BYPASS (+2), PRINT (+2), SESSION (+7), SMS (+7), TRAFFICMAN (+8), TRANSLATION (+1), URL (+5)
  • VALID_LOG_TYPES count — 25 → 26 (added NEXUS)
  • LOG_TYPE_FIELDS count — 24 → 26 (added NEXUS and ENC)
  • get_session_report() extended — Added optional org_id, user_id, and hierarchy parameters. org_id/org_name are mutually exclusive; user_id/username are mutually exclusive. hierarchy param enables subtree reporting (undocumented API feature).
  • MCP or None normalization — All optional string parameters in silo_mcp/tools/orgs.py now use param or None to prevent empty-string validation errors when AI assistants pass "" for omitted optional params.
  • a8_download_file and a8_download_harvest_result MCP tools — output_path parameter is now optional. When omitted:
  • a8_download_file saves to temp directory using the original filename from Silo storage metadata (falls back to file ID if metadata unavailable)
  • a8_download_harvest_result saves to temp directory as harvest_<task_id>.zip
  • Both tools add numeric suffixes (_1, _2, etc.) to avoid overwriting existing files

[0.8.8] - 2026-04-13

Added

  • 5 new MCP tools (55 total, up from 50):
  • a8_list_users_recursive (User Management) — Recursively lists users across an org and all its sub-orgs. Params: org, max_depth (default 5), include_suspended (default True). Returns a flat list with org, username, email, given_name, surname, is_suspended, last_authorized_ts.
  • a8_get_org_tree (Organization Management) — Returns the full org hierarchy as a nested dict. Params: org_name, max_depth (default 5). Returns {"org_name", "current_users", "children": [...]}.
  • a8_resolve_org (Organization Management) — Resolves an ambiguous org name to its full canonical path. Params: org_name. Returns {"org_name", "org_id", "parent_org_name", "candidates": [...]}. candidates is populated only when the name is ambiguous.
  • a8_batch_suspend_users (Batch Requests) — Suspends multiple users in a single API round-trip. Params: usernames (list of str). Returns per-username result dicts.
  • a8_batch_delete_users (Batch Requests) — Deletes multiple users in a single API round-trip. Params: usernames (list of str). Returns per-username result dicts.
  • a8_upload_file content parameter — Accepts an optional content: str as an alternative to file_path. Provide exactly one of file_path or content; providing neither or both raises ValueError.
  • run-mcp.sh now appends stderr to /tmp/mcp-server.log for post-disconnect diagnosis.

[0.8.7] - 2026-04-01

Fixed

  • org.update — API returns flat dict; SDK expected list → now checks dict first
  • delete_partner_sso_config — API returns {"deleted":1,"status":1} dict; SDK expected int → fixed type check
  • get_session_report — API error responses embedded in result dict were silently returned as success → now raises OrgManagementAPIError
  • delete_harvest_task — result extracted from wrong response index → fixed to use _extract_api_result
  • upload_file — omitted path param when value was "/" → now always sent
  • Postman FLOW download requests — three FLOW requests (Download File, Download Log File, Download Output File) used JSON command-array body on POST /getfile/; confirmed via live test that /getfile/ accepts multipart/form-data only (id + auth fields); all three corrected
  • Postman harvest task wire format — Create Asset Collection Task and FLOW — Create Visual Harvest Task had task_type/urls at command level and params as dicts; corrected to request_type inside task_params with {name, value} array format
  • docs/maintenance/api-recommendations.md — corrected session_report wire command from org.session_report to session_report; documented that include_children is silently ignored and :hierarchy is the real undocumented param

Added

  • BrowsingAPI.update_context() — modify an existing browsing context (browse_context_id, context_data, max_uses, expires, name, enabled); registered in command registry; exposed as a8_update_context MCP tool
  • extract_logs() include_suborgs parameter — optional bool; when True includes log records from child organizations; omitted from request when not provided
  • find_harvest_task() finished parameter — optional bool; when True filters to completed tasks only, when False filters to in-progress tasks only; omitted from request when not provided. Also exposed on a8_find_harvest_task MCP tool

Changed

  • MCP a8_upload_file, a8_find_files, a8_list_files — docstrings clarify that bucket_id is provisioned by Authentic8 Support; no list API exists

[0.8.6] - 2026-03-26

Added

  • silo_sdk/utils/validators.py — shared parameter validation helpers: validate_nonempty_string, validate_optional_string, validate_positive_int, validate_nonnegative_int, validate_token_format. Exported from silo_sdk.utils.
  • silo_sdk/base/types.py — 17 response TypedDicts exported from the public API: UserRecord, OrgRecord, FileRecord, TaskRecord, LogEntry, ContextRecord, EgressInfo, SSOConfig, ProxyRecord, PhoneEntry, and more.
  • silo_sdk/utils/formatting.py — format_table() and to_csv() shared by scripts.
  • silo_sdk/utils/org.py — walk_org_tree() (BFS generator) and print_org_tree().
  • BaseAPIClient._build_payload() — convenience method for constructing single-command API payloads; eliminates repeated [{"command": cmd, **params}] boilerplate.
  • 10 new MCP tools (49 total, up from 39): a8_update_context, a8_list_egress_locations, a8_create_research_session, a8_wait_for_harvest_task, a8_download_harvest_result, a8_get_valid_task_types, a8_get_valid_task_params, a8_list_files, a8_get_log_types, a8_get_extract_logs_info
  • 4 new operational scripts:
  • scripts/audit_org_users.py — compliance audit: inactive, suspended, missing-field users
  • scripts/batch_user_provisioning.py — bulk user creation from CSV with dry-run
  • scripts/analyze_log_storage.py — log type availability and sequence info
  • scripts/compare_org_configs.py — proxy policy / user count drift across org hierarchy
  • examples/batch_operations_demo.py — bulk context creation with per-item error capture, retry, and cleanup summary.
  • MCP tests: tests/test_mcp_credentials.py and tests/test_mcp_tools.py (skipped automatically when mcp package is not installed).
  • tests/test_utils_formatting.py and tests/test_utils_org.py.

Changed

  • All 39 MCP tools now translate SDK exceptions to MCP-friendly messages: ValidationError / ConfigurationError → ValueError; SiloError → RuntimeError.
  • scripts/move_users.py — per-user progress feedback during execution.
  • examples/harvest_demo_async.py — added timeout handling (asyncio.wait_for), partial-failure handling, and progress note.
  • scripts/move_users.py and scripts/session_report.py — table output now uses shared format_table() from silo_sdk.utils.formatting.
  • CI matrix — dropped Python 3.9 (EOL October 2025); minimum is now Python 3.10. Updated requires-python = ">=3.10".
  • black upgraded >=26.3.1. Pre-commit rev synced.

Fixed

  • tests/test_api_tag_on_static_method — callable(staticmethod) guard for Python 3.9 (now skip-pathed via sys.version_info; no longer breaks on 3.10+ either).
  • tests/test_import_error — changed mock.patch(string) to mock.patch.object(module) for reliable behavior across Python 3.10–3.13.
  • tests/test_mcp_tools.py — added pytest.importorskip("mcp") guard so CI does not fail when the mcp package (in [mcp-server] extra) is not installed.
  • Postman collection flow assertions — corrected Log Pipeline and Context Lifecycle flows: get_log_info (non-existent command) → extractlog probe; result array → result.logs array; AUTH,SESSION multi-type → single AUTH for this token.
  • docs/getting-started/authentication.md and docs/concepts/tokens.md — removed get_log_info (confirmed via live API testing that this command does not exist).
  • docs/maintenance/api-recommendations.md — updated Log Sequence Metadata section to reflect SDK workaround via extractlog probe (v0.8.5+).
  • Dependency audit — a known vulnerability in pygments is deferred pending an upstream fix.

[0.8.5] - 2026-03-25

Added

  • BrowsingAPI.update_context() — new method to modify an existing browsing context. Accepts browse_context_id plus any combination of context_data, max_uses, expires, name, and enabled. Only supplied fields are updated; omitted fields are unchanged. Registered in command_registry.py.
  • extract_logs() include_suborgs parameter — optional bool that, when True, includes log records from child organizations in the extraction result. Omitted from the request when not provided (no change to existing behavior).
  • single harvest task type — added to VALID_TASK_TYPES. Single-URL non-recursive fetch; uses wget_params; available from all egress locations (unlike asset).
  • VALID_ASSET_EGRESS_LOCATIONS — new constant in egress_validation.py listing the six datacenter locations valid for asset tasks: Singapore, Dubai, Frankfurt, Sao Paulo, Johannesburg, New York City / New York, NY.
  • Three missing egress locations added to VALID_EGRESS_LOCATIONS for video/visual/single tasks: Kuwait City, La Paz, Monterrey (confirmed from official API documentation Appendix A).
  • 39 new unit tests across test_browsing_api.py, test_egress_validation.py, test_harvester_api.py, test_log_extraction_api.py, and test_user_management_api.py. Total: 1,124 tests, 99.28% coverage.
  • Postman collection v0.8.5 — session_report request corrected, new Update Context request added to Browsing Isolation section, include_suborgs shown in Extract Logs example.

Changed

  • get_user() signature — username and email are now keyword-only and mutually exclusive. Live API testing confirms the API returns an error if both are supplied simultaneously. Pass exactly one: api.get_user(username="u@x.com") or api.get_user(email="u@x.com").
  • get_session_report() signature — include_children parameter removed. Confirmed via live API testing this was never a real API parameter and was silently ignored by the server. The method now accepts org_name, start_date, end_date, and username.
  • Asset task egress validation — create_harvest_task(task_type="asset", ...) now raises ValidationError if the supplied egress_info["name"] is not one of the six valid asset egress locations (source: Harvester API Documentation Appendix A, Feb 2026). Previously any location from the full list was accepted and silently sent to the API.
  • VALID_EGRESS_LOCATIONS reorganized — list sorted consistently within regions; three previously missing locations added.

Fixed

  • scripts/session_report.py — removed --no-children CLI flag and include_children kwarg that was silently ignored by the API.
  • scripts/move_users.py and examples/user_demo.py — get_user() calls updated from positional argument to keyword argument (username=) to match the new signature.
  • silo_mcp/tools/orgs.py a8_get_session_report — removed include_children from the MCP tool signature.

Breaking changes

  • get_user(username) positional call → use get_user(username=username) or get_user(email=email). Passing both raises ValidationError.
  • get_session_report(include_children=...) → remove the argument; it no longer exists.
  • create_harvest_task(task_type="asset", egress_info={"name": "Tokyo"}) → raises ValidationError. Asset tasks must use one of the six valid datacenter locations.

[0.8.4] - 2026-03-16

Added

  • update_partner_sso_config — new OrgManagementAPI method to update an existing Partner SSO configuration. All IdP fields (idp_name, idp_login_url, idp_cert, vanity_url, new_org_name, parent_org_name) are optional; only supplied fields are sent. Also works to add SSO to an existing org that has no SSO config yet.
  • delete_partner_sso_config — new OrgManagementAPI method to permanently delete a Partner SSO configuration, its partner user, and the org itself. Irreversible.
  • Both new methods registered in command_registry.py and exposed as MCP tools (a8_update_partner_sso_config, a8_delete_partner_sso_config) — MCP server now has 37 tools.
  • manage_sso.py — new standalone script providing a full CLI for all 6 Partner SSO API operations (create, get, update, delete, enable, disable) plus an import-metadata subcommand that parses live SAML IdP metadata XML (from file or URL) to auto-populate SSO config.
  • silo_sdk/utils/saml.py — new SAML IdP metadata parsing utilities (fetch_metadata_url, parse_saml_metadata) used by manage_sso.py and the a8_parse_saml_metadata MCP tool.
  • a8_parse_saml_metadata MCP tool — parses a SAML IdP metadata XML document and returns structured IdP config (entity ID, login URL, certificates).
  • update_collection_examples.py — repeatable script that runs Newman against the Postman collection, captures real sanitized API responses, and writes examples back to the collection JSON. Supports multi-pass error capture, SSO org state persistence, and SAML metadata fetching.
  • docs/maintenance/api-recommendations.md — new page documenting confirmed API gaps (org.update_settings missing, list_harvest_tasks missing, get_log_info missing) and resolved gaps (proxy policy write ops confirmed as policy_proxies.set/add/delete).
  • 20 new unit tests for SSO methods (1055 total).

Changed

  • create_partner_sso_config / get_partner_sso_config docstrings — documented the full real API response schema (SP_cert, SP_entity_id, a8_portal_url, a8_postback_url, partner_SSO_sign_cert) sourced from official API documentation and live reference code.
  • get_partner_sso_config docstring adds behavioral note: the API returns an error (not empty dict) when SSO is disabled for the org.
  • create_org() docstring corrected — always creates a sub-org (not top-level); documents parent defaulting to token scope when omitted, SCIM group provisioning use case, and vanity_url as optional here vs required for SSO.
  • get_log_sequence_info() reimplemented — the get_log_info command is not recognized by the ext API. Now implemented as a CONVENIENCE method that probes via extractlog(start_seq=0, limit=1, type=AUTH). Returns min_seq, is_more, next_seq; max_seq and total_logs are explicitly None (not available via ext API).
  • extract_logs() bug fixed — was failing to unwrap the {"result": {...}} response envelope, causing logs to always be empty and is_more/next_seq to be None. The fix adds a single unwrap step consistent with how all other API modules handle responses.
  • export_logs.py fixed — show_info() updated to display earliest seq / is_more / next_seq instead of the unavailable min_seq/max_seq/range. Default start_seq logic now uses or 0 to gracefully fall back when no logs are found at the probe point.
  • a8_create_org MCP tool description updated to match corrected create_org() docstring.
  • a8_extract_logs MCP tool — corrected Returns (removed fabricated total_count; documents actual logs/is_more/next_seq fields).
  • a8_get_log_sequence_info MCP tool — updated to reflect probe-based implementation; max_seq/total_logs documented as None.
  • create_harvest_task docstring — corrected wire key names (wget_params/vid_params not asset_params/video_params); full wire format example now shows correct task_params nesting.
  • download_file docstring — added Note documenting POST /getfile/ endpoint with form-data id+auth (not a command-array request).
  • create_context docstring — added Note about GET /ctx/ shorthand with response= parameter; updated create_ctx_url to cross-reference.
  • create_partner_sso_config docstring — parent_org_name clarified as required in practice.
  • docs/concepts/wire-protocol.md — new Non-Command-Array Endpoints section documenting POST /getfile/, POST /putfile/, and GET /ctx/ with response= parameter table.
  • MCP a8_create_harvest_task — warns against invalid task_type values (screenshot, pdf, mhtml); a8_create_partner_sso_config clarifies parent_org_name requirement.
  • Postman collection updated: 60 standalone requests now have real sanitized API response examples; harvest task wire format corrected; Download File corrected to POST /getfile/; Upload File form field names corrected (name/path); GET /ctx Shorthand updated with response=url parameter.
  • scripts/README.md — update_collection_examples.py documented with usage examples, SSO org reset procedure, and required env vars.
  • Version bumped to 0.8.4 across pyproject.toml, silo_sdk/__version__.py, User-Agent strings, silo_mcp/__init__.py, config files, and docs.

Removed (fabricated commands that do not exist in the ext API)

  • update_org_settings() removed from OrgManagementAPI — the org.update_settings command is not recognized by the ext API. Org settings (session limits, MFA, download policies) are not configurable via the API. a8_update_org_settings MCP tool removed.
  • list_harvest_tasks() removed from HarvesterAPI — the list_harvest_tasks command is not recognized by the ext API. Use find_harvest_task(task_id) for point lookup, or extract HARVEST log type entries to find task IDs. a8_list_harvest_tasks MCP tool removed.
  • settings param removed from create_org() — was unverified and unused.

Added (proxy policy management — confirmed real API commands)

  • get_proxy_policy() — new OrgManagementAPI method using policy_proxies.get
  • set_proxy_policy() — replaces entire proxy list (policy_proxies.set)
  • add_proxy_policy() — appends proxy objects; multiple in one call (policy_proxies.add)
  • delete_proxy_policy() — removes by name; multiple names in one call (policy_proxies.delete); always returns HTTP 200 with proxies_deleted and proxies_not_found arrays
  • All four methods exposed as MCP tools: a8_get/set/add/delete_proxy_policy — MCP server now has 39 tools
  • Proxy object schema documented: name (required, unique) + location.address (required); port and type optional (http/https/socks/socks4/socks5); HTTPS cert CN must match address
  • docs/concepts/wire-protocol.md — Proxy Policy Commands section with schema, type table, delete response format, and hierarchy aggregation note

Added (browsing policies)

  • docs/concepts/browsing-policies.md — new reference page documenting all confirmed browsing context policy types: readonly, file_transfer, clipboard, browser_chrome (standard/seamless/minimal), domain_allow, domain_block, ribbon_*
  • Seamless UI constraint documented: browser_chrome: seamless only available for non-catchall users; catchall users are always forced to minimal (Ribbon Mode)
  • egress_region validation added to BrowsingAPI.create_context() — validates against VALID_EGRESS_LOCATIONS (shared Silo Workspace egress network). Documents mixed-licensing caveat: per-user entitlements are enforced at launch, not at SDK level.

Added (test coverage and quality)

  • tests/test_saml.py — 29 new tests for silo_sdk/utils/saml.py (0% → 100% coverage)
  • tests/test_coverage_gaps.py — 24 new tests covering remaining gaps in org_api, extraction_api, file_api, tags, harvester_utils, harvester_api, log_schemas, key_management
  • Overall coverage: 96.4% → 99.3%; total tests: 1,105 passing

Added (Postman collection and update tooling)

  • Postman collection v2 merged from manual review: org requests in "Org Structure" subfolder, corrected proxy policy commands, new GET /ctx with X-Auth Header, Create Organization, Add/Delete Proxy Object, Get API Session Report requests; List Tasks / Update Org Settings removed (commands do not exist)
  • ctx_url env var added to all four Postman environment files — enables multi-environment GET /ctx testing without hardcoded production URLs
  • proxy_name env var added to all four Postman environment files
  • Example naming convention updated: "Valid Response" / "Error: <summary>" replaces "200 OK – Real Response" / "400 BAD REQUEST – Error Response"
  • API-level error detection in update script: checks response[1]["error"] and nested result.error — captures errors that HTTP 200 responses previously hid
  • Eng environment support in update_collection_examples.py: A8_CONFIG_ENV=eng uses .env.eng overrides; env-specific state files (.collection_update_state.eng.json); Newman env URLs derived from A8_API_URL; 57/60 standalone requests updated against eng
  • dest_path changed from /harvester_results/ to /postman/ in all environment files and the Newman env builder

Changed (API correctness and documentation)

  • create_org() docstring corrected: always creates sub-org; vanity_url optional here but required for SSO; org hierarchy root documented; SCIM context added
  • browser_chrome policy type added to BrowsingAPI class docstring (3 values: standard, seamless, minimal); Seamless UI auth constraint documented
  • add_proxy_policy docstring — clarifies multiple proxies can be added in a single call
  • delete_proxy_policy docstring — clarifies multiple names can be deleted in a single call
  • Phone area code validation documented: 555 area codes are rejected by the user management API (not enforced by Admin Console); all SDK examples and tests updated to use 888 area code
  • Egress region names corrected across egress_validation.py and isolation_api.py: Asia-Pacific, Africa & Middle East, Central & South America
  • docs/maintenance/api-recommendations.md expanded with: proxy policy resolution, list_harvest_tasks confirmed missing with HARVEST log workaround, per-user egress availability gap, role-based permission assignment gap with Claims-based provisioning customer request

[0.8.3] - 2026-03-04

Added

  • Postman API Reference Collection — fully audited and corrected; 112 requests across 7 numbered folders, 100% Newman pass rate against Production
  • All request bodies corrected to use flat wire format (params alongside "command", not nested under "data")
  • create_context fixed: "user" / "urls" (array) instead of "username" / "url" (scalar)
  • Harvest task types corrected: "visual" / "asset" / "video" only; "screenshot" removed
  • SSO configuration chain fixed: uses org_name (not sso_config_id, which doesn't exist)
  • Auto-generated test_org_name and test_sso_org_name in pre-request scripts
  • Proxy policy and org.update_settings tests made graceful for permission-limited accounts
  • GET /ctx shorthand URL corrected (removed erroneous /api/ prefix)
  • Find Files — Date Range request added demonstrating file_type, :created_before, :created_after filter params
  • Newman testing guide (docs/postman/newman-testing.md) — setup, commands, environment variable mapping, CI/CD GitHub Actions workflow, known limitations
  • Wire format Note: sections added to five SDK methods documenting Python→wire field name and type differences:
  • BrowsingAPI.create_context: username→"user", url→"urls" (array), max_uses placement
  • HarvesterAPI.create_harvest_task: valid task_type values, task_params→vis_params mapping
  • LogExtractionAPI.extract_logs: log_types list→comma-joined string, date→epoch transforms
  • OrgManagementAPI.create_partner_sso_config: idp_name→"IdP_name" (case-sensitive)
  • FileAPI.find_files: file_type→"type", created_before→":created_before" (colon prefix)
  • Attributes: sections added to BrowsingAPI, HarvesterAPI, and LogExtractionAPI class docstrings so mkdocstrings renders VALID_TASK_TYPES, VALID_VISUAL_PARAMS, VALID_LOG_TYPES as structured tables in the MkDocs API reference
  • MkDocs nav: new "Postman & Newman" section linking to the Newman testing guide

Fixed

  • .mcp.json pointed to outdated repository path; corrected.
  • MCP server mcp-server extras not installed; pip install -e ".[mcp-server]" now required for the MCP server to start (installs mcp, fastapi, uvicorn)
  • Wire format example in developer docs showed incorrect "data": {…} nesting; corrected to flat params
  • Wire format example in docs/concepts/wire-protocol.md showed wrong listusers structure
  • docs/getting-started/authentication.md: API_URL example had erroneous /api/ suffix
  • docs/getting-started/quickstart.md: misleading task_type="screenshot" → task_type="visual"
  • docs/concepts/async.md: task_type="screenshot" → task_type="visual"
  • docs/getting-started/quickstart.md and 13 other files: stale v0.8.1/v0.8.2 version references updated to v0.8.3
  • User-Agent string defaults updated from silo-sdk/0.8.1 → silo-sdk/0.8.3 in api_client.py, config.py, config_builder.py, config/default.json, config/production.json
  • silo_mcp/__init__.py version bumped to 0.8.3

Changed

  • Postman environment defaults updated: org_name maps to A8_TOP_ORG (not A8_ORG_VANITY_URL)
  • Postman collection info.version set to 0.8.3
  • Developer tooling documentation expanded: flat-param rule, create_context exception, org vs org_name param distinction, A8_TOP_ORG vs A8_ORG_VANITY_URL distinction

[0.8.2] - 2026-03-03

Changed

  • Simplified README for public PyPI project description
  • Removed internal email references from all public-facing files
  • Fixed Documentation URL to point to GitHub Pages
  • Updated Dockerfile maintainer labels

[0.8.1] - 2026-03-03

Package rename: outdated repository path → silo-sdk.

Changed

  • Package renamed from its outdated repository path to silo-sdk
  • Import path changed from a8_apis to silo_sdk
  • Exception base class renamed from A8APIError to SiloError
  • A8APIError kept as backward-compatible alias
  • Repository renamed to silo-sdk-python
  • User-Agent string updated to silo-sdk/0.8.1

Migration

# Old
from a8_apis import BrowsingAPI, A8APIError

# New
from silo_sdk import BrowsingAPI, SiloError

# A8APIError still works as alias
from silo_sdk import A8APIError  # backward compat

[0.8.0] - 2026-03-03

Project reorganization and documentation overhaul.

Added

  • 6 API quick reference guides (browsing, user management, org management, file storage, log extraction, decryption)
  • Zensical migration readiness assessment (docs/maintenance/zensical-migration.md)
  • Archived tools documentation page (docs/development/archived-tools.md)

Changed

  • Version rolled back from 1.0.0 to 0.8.0 to reflect pre-production beta status
  • pyproject.toml classifier changed to Development Status :: 4 - Beta
  • .gitlab-ci.yml moved to .gitlab/ci.yml for better organization
  • Aligned ignore file patterns across .gitignore, .dockerignore, .claudeignore
  • Archived tools/postman_validator/ (restored via git history if needed)
  • Archived Documentation/Authentic8_Unix_Log_Extract_Package_1.0.3/ to Documentation/archive/
  • Removed tools/ exclusions from .pre-commit-config.yaml
  • Improved 14 documentation pages for user-friendliness and accuracy
  • Documentation site expanded to 38 pages

Fixed

  • Broken links in docs/development/archived-tools.md
  • Outdated version references across documentation

[0.7.0] - 2026-03-01

MkDocs documentation portal, MCP server, and CI/CD automation.

Added

  • MkDocs developer portal (28 pages) with Material theme and mkdocstrings
  • Getting started guides (installation, quickstart, configuration, authentication)
  • How-to guides (bulk harvest, decrypt logs, export logs, manage users)
  • Concepts documentation (async, errors, tokens, wire protocol)
  • Auto-generated API reference for all 7 modules
  • Maintenance playbooks (branch protection, CI runbook, release checklist)
  • MCP server with 34 tools exposed via Model Context Protocol
  • Dual transport: stdio + SSE (Server-Sent Events)
  • FastAPI-based server implementation
  • Reliable environment loading wrapper script
  • CI/CD automation:
  • GitHub Actions workflows for quality checks, security audits, docs deployment
  • Weekly dependency audit workflow
  • GitLab CI/CD configuration with Component Catalog structure
  • templates/sdk-test.yml reusable CI component
  • GitHub Pages deployment via mkdocs gh-deploy
  • PyPI packaging with OIDC Trusted Publisher (later disabled for release-only distribution)

[0.6.0] - 2026-02-28

Native log decryption and log type schemas.

Added

  • Native log decryption (a8_apis/logging/decrypt.py):
  • Standard decryption: EC + HKDF-SHA384 + AES-256-GCM
  • Legacy decryption: seccure/secp256r1
  • standard_decrypt() — in-memory decryption
  • standard_decrypt_chunked() — 32 MB streaming for large files
  • decrypt_video_file() — atomic write with temp file
  • load_private_keys(), decrypt_log_entry(), decrypt_logs()
  • Private key file format: name=value pairs in pvtkey.txt
  • Log type CSV schemas (a8_apis/logging/log_schemas.py):
  • Canonical field ordering for 24 log types
  • 25 total log types including APP_LAUNCH, EVENT, EXTENSION
  • Schemas synced with Authentic8 package v1.0.3
  • Optional package extras: [decrypt] and [legacy-decrypt]
  • run_after parameter for delayed harvest task execution (Unix epoch or ISO 8601)
  • All 30+ vis_params and video_params synced with Harvester API v2.14
  • Authentic8 Log Extract Package v1.0.3 added as reference
  • Python 3.9-3.13 CI test matrix (expanded from 2 to 5 versions)

[0.5.0] - 2026-02-20

Standalone scripts, SDK examples, and packaging.

Added

  • 8 standalone scripts in scripts/:
  • export_logs.py — log extraction with pagination, resume, decryption, proxy support
  • key_manager.py — CLI for managing private keys and API tokens
  • bulk_create_contexts.py — bulk browsing context creation from URL list
  • session_report.py — organization session report generator
  • file_manager.py — file storage CLI (list, search, download, info)
  • scheduled_visual_harvest.py — daily visual captures with run_after scheduling
  • decrypt_files.py — batch log file decryption
  • move_users.py — user migration between organizations
  • SDK demos in examples/:
  • user_demo.py, org_demo.py, log_demo.py, decrypt_demo.py
  • browsing_demo.py, file_demo.py, config_demo.py
  • harvest_demo_sync.py, harvest_demo_async.py
  • CONTRIBUTING.md with development workflow
  • .env.example template with all A8_* environment variables
  • Unified Postman API Reference Collection (100% SDK coverage)

Changed

  • examples/ renamed to sdk_examples/ for clarity (reverted to examples/ in cleanup)
  • Repository URLs updated to reflect current hosting
  • Removed legacy Postman collections (replaced by API Reference Collection)

[0.4.0] - 2026-02-15

Security hardening and near-complete test coverage.

Security

  • 6 CVEs fixed:
  • urllib3 CVE-2026-21441 (CVSS 8.9): DoS via decompression bomb on redirect responses; fixed in urllib3 2.6.3
  • certifi CVE-2024-39689 (CVSS 7.5): Untrusted GLOBALTRUST root certificate (MITM risk); fixed in certifi 2024.07.04
  • aiohttp CVE-2024-52304: Request smuggling via chunk extension parsing
  • aiohttp CVE-2025-53643: Request smuggling via chunked trailer parsing; fixed in aiohttp 3.12.14
  • aiohttp CVE-2025-69223: Zip bomb DoS via unbounded decompression; fixed in aiohttp 3.13.3
  • cryptography CVE-2026-26007 (CVSS 8.2): Subgroup attack on SECT binary curves leaks private key bits via ECDH; fixed in cryptography 46.0.5
  • All dependencies pinned with upper bound constraints
  • Replaced random with secrets for cryptographic operations
  • Fixed command injection vulnerability in setup_venv.py

Added

  • 76 additional tests pushing coverage from 94% to ~99%

Changed

  • aiohttp and certifi made mandatory dependencies (no longer optional)
  • All security audit findings resolved
  • 3 flake8 unused import warnings fixed

[0.3.0] - 2026-02-10

Test coverage, quality gates, and SDK method tagging.

Added

  • SDK method tagging system:
  • @api_tag decorator for method classification (API_COMMAND, CONVENIENCE, ASYNC_VARIANT, UTILITY)
  • COMMAND_REGISTRY — single source of truth for SDK method to wire command mapping
  • Unified Postman collection with SDK generator and validation tools
  • Pre-commit hooks: black, isort, flake8, mypy, bandit, pylint
  • pytest-asyncio for async test support
  • Custom developer tooling slash commands for development workflows

Changed

  • Test coverage pushed from ~60% to 94.22% (500+ tests)
  • Fixed 19 async test failures caused by mock setup bugs
  • MyPy type annotations added across the entire codebase (61 errors to 0)
  • types-requests added to dev dependencies for mypy stub resolution

[0.2.0] - 2026-02-05

All 6 API modules functional with async support.

Added

  • Silo for Research session type in BrowsingAPI
  • Full async support in HarvesterAPI and FileAPI
  • Claude Code agents for development workflow

Changed

  • Async utility functions consolidated into HarvesterAPI class (removed 600+ lines of duplicate code)
  • FileAPI refactored for improved reliability
  • HarvesterAPI end-to-end workflow verified

APIs Completed

  • Browsing Isolation API (a8_apis.browsing.BrowsingAPI)
  • User Management API (a8_apis.management.UserManagementAPI)
  • Organization Management API (a8_apis.management.OrgManagementAPI)
  • File Storage API (a8_apis.storage.FileAPI)
  • Log Extraction API (a8_apis.logging.LogExtractionAPI)
  • Web Harvesting API (a8_apis.harvesting.HarvesterAPI)

[0.1.0] - 2026-01-30

Initial SDK framework.

Added

  • Base API Client (a8_apis.base.BaseAPIClient):
  • HTTP session management with retry logic
  • Authentication handling via Bearer tokens
  • Request/response logging
  • Rate limiting support
  • Comprehensive error handling
  • Configuration system (a8_apis.utils.config):
  • JSON configuration file loading
  • Environment variable substitution (${VAR} and ${VAR:-default})
  • Validation via validate_config_for_api()
  • Exception hierarchy (a8_apis.base.exceptions):
  • Base A8APIError with HTTP status and request ID tracking
  • Module-specific exceptions (BrowsingAPIError, FileAPIError, etc.)
  • Initial implementations of BrowsingAPI, FileAPI, HarvesterAPI
  • Setup script with virtual environment creation
  • Project structure: a8_apis/ package with base/, browsing/, storage/, harvesting/, logging/, management/, utils/ submodules

Package Metadata

  • License: MIT
  • Python: 3.9+ (initial release; minimum raised to 3.10 in v0.9.1)
  • Dependencies: requests, urllib3, aiohttp, certifi, python-dotenv