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 TOOLshows 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-toolsor the server options. The error for an unknown argument name now points at it.
Changed¶
- The
docsanddevextras cappymdown-extensionsbelow 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
inputSchemanow 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 examplelimit1 to 1000 andstart_seqat least 0 ona8_extract_logs. Accepted input is unchanged, with the one exception below. a8_update_contextrefuses amax_usesbelow 1. It used to pass any integer to the platform, which stores0or 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, asa8_create_contextalready did. To switch a context off, passenabled: false.- Tool descriptions cover the rules that used to fail calls.
a8_get_session_reportstates that it takes at most one identifier, that its dates areMM-DD-YYYY, and that it returns aggregates only.a8_extract_logsstates thatstart_seqis required, thatstart_date/end_datecount days before today, how to page withis_more/next_seq, which log type answers which question (SESSIONfor egress and execution server;LOCATION_CHANGEis page navigation), and which types carry browsing history. Return-value documentation was corrected where it named fields the platform does not send, includinga8_get_session_report,a8_upload_file,a8_modify_file,a8_list_files,a8_get_user,a8_modify_useranda8_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
--describecommand for the tool. A missingstart_seqona8_extract_logspoints ata8_get_extract_logs_info. MCP clients and--callreceive the same text. - A days-ago value too large to be a day count gets a clear error. Passing an epoch timestamp as
start_dateorend_datetoextract_logs()used to raise "days=...; must have magnitude <= 999999999". It now raisesValidationErrorexplaining that the value is a number of days before today, not a date or timestamp.
Security¶
- The
mcp-serverextra requiresmcp1.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 storedcontext_datawith the one you send, then re-applies the creation defaults. An update that sent onlyurlsremoved the context'srestrict_ips(its IP lock) and its egress, and turned atoolbox-standalonecontext intosilo-ruby. The SDK,a8_update_contextand their examples now say to send the completecontext_data.update_context()logs a warning whencontext_datahas nosession_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.expiresgiven 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, includinga8_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
categorieson a context may use lists and null in the SDK,a8_create_context,a8_update_contextanda8_create_browsing_url:availabilityandconnectivityaccept a single value, a list ornull, andegress_info.categoriesmay benull, as the platform allows.protocolstays 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 defaultresponsefor the/ctx/endpoint isurl. 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_contentreturned it as the file's text. All download paths now raiseFileAPIErrorwith the platform's error and malware details, and leave no file behind. - A download shorter than its
Content-Lengthwas retried, then lost. For some files the platform'sContent-Lengthexceeds 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 raisesFileAPIErrorwith 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 numericexpire_tsfailed on the platform. Numbers are now sent as strings. All five accepted forms are documented: epoch seconds,now+SECONDS,+SECONDSto extend the current expiry,resetfor the bucket default, and an ISO 8601 date.get_file_info()andmodify_file()reported a platform error as "Unexpected response format", with the full response in the message. They now raiseFileAPIErrorwith 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:nameis matched exactly (ignoring case), with no wildcards, so"*.pdf"matches nothing.pathmatches files directly in that folder only.file_typefilters byfileordirectory, not by MIME type or extension.metadata_filtershave 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. Whenprotocolwas not given, the SDK sent"protocol": nullon 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
cookiesstring.notesis accepted on asset, single and video tasks.run_afteraccepts float epochs and any ISO 8601 date with a timezone (offsets, fractional seconds), and refusesTrue, which was read as 1970 and ran the task at once, and a value with surrounding whitespace. - Options set to
Falsewere sent and read as enabled. The platform treats an option's presence as on, soall_files=Falseturned directory output on. Top-level options set toFalseorNoneare no longer sent. egress_info.server_seton a harvest task is removed before sending. The SDK warned that it would be ignored, then sent it, and the platform rejected the task.recursiveon a single task is refused with a clear error, byTaskBuilderand bycreate_harvest_task()alike, since the platform always rejects recursion for single tasks.levelalone 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 sendwait_nav: Trueas 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 raiseValidationErrornaming the option. - Documentation corrections:
wait_navandxfftake a value. Videocookiestakes the cookie file's content, not a path.all_files=Truereturns a directory thatdownload_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 ignoresfinished. 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()requiredgiven_nameandsurname; the platform does not. Both are now optional inadd_user(),a8_add_useranda8_bulk_add_users.emailstays required, as the platform requires it.list_users()documentation said lockout fields were missing. Confirmed by live API testing: each user record fromlist_users()has the same fields asget_user(), includingis_locked,failed_login_attempts,oob_lockedandoob_lock_expires_at.modify_user()replaces all custom fields. Custom fields left out ofcustom_fieldsare 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()'scurrent_userscounts the whole sub-tree.- Session report:
end_dateis exclusive, andorg_idcovers that organization only, whileorg_nameincludes its children. - Unsuspending an active user returns a server error.
bypass_codeis always returned.
Log extraction¶
- Documentation said leaving out
include_suborgsreturns only the named organization. It includes sub-organizations. Confirmed by live API testing. Passinclude_suborgs=Falsefor the named organization only. start_datecurrently has no effect whenstart_seqis sent, andstart_seqis always sent. Confirmed by live API testing; the documentation now says so. Useend_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
actionandlabelon ADMIN_AUDIT andtextandfilenameon NEXUS. Single-type exports anda8_export_logs_csvnow 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_csvgathers rows in a temporary file rather than in memory before writing. a8_export_logs_csvnow 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_seqis 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()'sversionis a string.end_dateis ignored whenend_seqis 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_passwordandbypass_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_beforeandlimit, which the platform ignores, so it returned every file and then pointed later file requests at whichever one came first. It now sendstype,:created_afterand:created_before, and leavesfile_idalone. - Extract Logs — Date Range sent
start_seqwithstart_time, so the time window was ignored. It now sends the time window alone.
Scripts¶
scheduled_visual_harvest.py --xfftakes a value. It was an on/off switch, but the platform requires a value for this option, so a capture with--xffalways failed.batch_user_provisioning.pyno longer requiresgiven_nameandsurname. Onlyusernameandemailare required, as on the platform.extract_all_logs.py --daysandexport_logs.py --days-backsay 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.pybrings the session and usage reports together. One CLI with three subcommands:session,org-usageanduser-usage. Each takes the same flags as the script it replaces and keeps its output, error messages and exit codes.scripts/contexts.pycreates and manages browsing contexts.createandbulktake over from the two context-creation scripts with the same flags. New subcommands:getprints a context's details as JSON,updatechanges its maximum uses or expiration, anddeleteremoves it.updateanddeleterefuse to run without--yes(exit status 2). With--yesthey first print the target API URL and its environment (eng, qa or production) to stderr.scripts/file_manager.pycan upload, modify and delete files.upload --file LOCAL [--dest-path DIR] [--name NAME]adds a file and runs without confirmation.modifychanges a file's name, folder, content type or expiry (--expire-ts now+SECONDS).deleteremoves a file permanently.modifyanddeleterequire--yesand 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.pyhas--helpand--dry-run.--dry-runlists 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-toolsshows 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 TOOLruns 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--argsor--args-file; any tool that is not read-only is refused without--yes; credentials in the output are redacted unless--revealis given, and tools that return a new credential (a8_reset_pin,a8_add_user,a8_bulk_add_users, anda8_batch_requestcontainingreset_pinoradduser) 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 aseng,qaorproduction.- 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,--yesand--reveal, output and exit codes, troubleshooting, and when a script inscripts/is the better fit. -
The MCP server can serve HTTPS, and can require client certificates.
--ssl-certfileand--ssl-keyfile(orMCP_TLS_CERTFILEandMCP_TLS_KEYFILE) turn on TLS for thestreamable-httpandssetransports.--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 stdiorefuses the flags and ignores the variables.docker-compose.mcp-tls.yml, configured withMCP_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. Withvalidate_egress=True, or the newLIVE_EGRESS_VALIDATIONsetting, it askslist_egresses()what the user may actually select and raisesEgressNotOfferedError, a newValidationErrorsubclass, before creating a context the platform would refuse, naming what is offered. Catch the subclass to tell this refusal, whichvalidate_egress=Falseoverrides, 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 anegress_infothat names aserver_setand for a context created for an org rather than a user. It never blocks when it cannot answer: with nousername, 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 forassetandwget, the browsing pool forvisual,videoandsingle, for the newHARVEST_EGRESS_ORGsetting (A8_HARVEST_EGRESS_ORG), orTOP_ORGwhen 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 setHARVEST_EGRESS_ORGwhen the harvest token belongs to a sub-org ofTOP_ORG; otherwise the lookup finds nothing and the check is skipped. WithLIVE_EGRESS_VALIDATIONorvalidate_egress=True,create_harvest_task()andcreate_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; passwarn=Falseto 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()takesservice_type("egress"or"harvest-asset") to report a specific server pool. An unknown value raisesValidationErrorinstead of returning the empty list the platform sends.bulk_create_contexts()takesvalidate_egressand checks the shared egress once for the batch, before creating any context.- The examples and scripts can list live egress.
--list-egress --liveinbrowsing_demo.py,news_spider_harvest.pyandscripts/scheduled_visual_harvest.py;--validate-egressinscripts/contexts.py createandbulk. - The Postman collection documents
service_typeon List Egresses and adds List Harvest Egresses requests for each pool.
Changed¶
- Maintainer tools moved to
scripts/dev/.cleanup.py,validate_log_schemas.pyandrun_postman_eval.share 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 --helpprints 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 --callfor operations no script covers. Theuser-usageexamples now use the flags the script accepts (--no-suspended,--sort time). -
bulk_create_contexts()logs an egress warning once per batch. An unknownegress_regionor an unavailable category used to be reported again for every context in the batch; it is now reported once. -
--liveon its own is now a usage error inscripts/scheduled_visual_harvest.pyand the browsing and news spider examples. It only modifies--list-egress, and was silently ignored without it. -
create_context()andbulk_create_contexts()reject an invalidsession_typelocally. A value other than"silo-ruby"or"toolbox-standalone", including an empty string, now raisesValidationErrorinstead of being sent to the platform. The MCP tools treat a blanksession_typeas unset.bulk_create_contexts()now raisesValidationErrorup front for an invalidegress_region,categoriesorsession_type, ascreate_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_taskanda8_harvest_urlrefuse an egress the pool's directory does not list, naming what it offers; passallow_unlisted_egress=trueto send it anyway.a8_list_egressestakesservice_type. -
scripts/scheduled_visual_harvest.pyand the news spider example warn on an unknown--egressinstead 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_sessionanda8_create_browsing_urlnow 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 takesallow_unlisted_egress=trueto create the context anyway. SetMCP_EGRESS_VALIDATION=offlineto keep only the built-in checks.a8_list_egress_locationsnow says it returns the SDK's compiled-in list and points toa8_list_egressesfor the live answer. -
The MCP server caps how long
a8_wait_for_harvest_taskanda8_harvest_urlwill wait. A wait aboveMCP_MAX_WAIT_SECONDS(default 1800, which isa8_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_urlchecks 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 calla8_wait_for_harvest_taskagain 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 inMCP_MAX_WAIT_SECONDSstops 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.pyandrun_postman_eval.sheach 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¶
-
HarvesterAPInow closes the file client it uses for downloads.HarvesterAPIcreates its ownFileAPIto fetch task results, and neitherclose(),cleanup_resources()nor leaving awith 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_LOCATIONSand the examples now use it; "New York City" on an asset task now logs a warning. -
Harvest egress validation reports a malformed
categoriesasValidationErrorinstead of crashing withAttributeError, 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 aserver_setis ignored by harvest tasks. -
examples/browsing_demo.pyruns 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 byget_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
connectivityno longer refuses the request.categories["connectivity"]was checked against the SDK's own list of four values and raisedValidationErrorfor anything else, though the platform treats connectivity as free-form and reports values that list does not have, such aswireless. 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, andavailabilityandprotocolare still checked strictly. -
Harvest waits no longer overshoot
max_wait_time.wait_for_completion,wait_for_completion_with_progressandwait_for_completion_asyncslept the fullcheck_intervalbetween 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_asyncchecks the status at least once. With acheck_intervallonger thanmax_wait_timeit made no status request at all and reported a timeout. -
HarvesterAPInames 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, butHarvesterAPIchecks its configuration with its own validator first, so it still raisedMissing required token: SCRAPE_TOKENwithout it. It now readsMissing required token: SCRAPE_TOKEN (set A8_SCRAPE_TOKEN), and likewise forBUCKET_ID.
Security¶
- Long harvest waits in the MCP server can no longer starve every other tool.
a8_wait_for_harvest_taskanda8_harvest_urlblock for as long as the caller asks (timeout_seconds, andmax_wait_secondswith 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_WORKERSenvironment 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
urllib3minimum 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 pinsurllib3to 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 combinedextract_logs()call fails as a whole when any single type is unavailable, most oftenENCon 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 intype_errorsinstead 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'sfallback_per_typeoption, 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_seqis 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 lowestnext_seqamong types still reportingis_more, so the next page may repeat rows of the types that were ahead — deduplicate byseq_id. With no type reporting more,next_seqis the lowestnext_seqany type reported, so a poller keeps advancing; it is thestart_seqyou passed only when no type reported one. - Types in
type_errorsare not covered bynext_seq. A failed type returned nothing, so resuming it from the mergednext_seqwould skip its rows. Re-request failed types from the originalstart_seq.is_moreis not forced toTruefor them, because a type that fails permanently (ENCon an org without encryption) would then never let a poller finish. -
merge_per_type_extracts(), exported fromsilo_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'sfallback_per_typenow 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 itsname, itspaththrough the location hierarchy (broadest to narrowest, so you can group by region without a static table), and thecategoriescombinations it offers. Give exactly one ofusername,user_id,org_idororg_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
errorelement inside an HTTP 200, and the token travels in anAuthorization: Bearerheader rather than in asetauthcommand. It needs anADMIN_TOKEN; a sync token is refused with403, as is an admin grant that does not cover users when you select byusernameoruser_id. check_egress_against_directory(egress_info, directory)validates anegress_infoagainst a directory you fetched, and is the authoritative counterpart to the compiled-in checks described under Changed below. Pass it the listlist_egresses()returned; it raisesValidationErrorif the location is not in it, or if a requestedconnectivity,availabilityorprotocolis 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,
EgressDirectoryEntryandEgressCategoryOption, describe what comes back. Note thatcategoriesis a list of objects coming out of the directory, while thecategoriesyou send in onEgressInfois 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. UserRecorddocuments the four lockout fields, which the platform has been returning onget_userall along. Checking onlyis_lockedwill 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_userandunsuspend_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 toextract_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
versionas a cache key yet. The method accepts aversionargument 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 sameversion— a client that skips the fetch on an unchangedversioncan therefore miss a newly added type. Call it withoutversionuntil that is fixed upstream. -
create_context()acceptsegress_info, the newer single-object form of egress selection. Previously the egress was chosen with two separate parameters,egress_regionandcategories. The object form takes the location asname, carries the samecategories, and additionally allowsserver_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_infowithegress_regionorcategories, 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. -
sovereignis accepted as an egressprotocol, alongsidedirectandtor, 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()andis_combination_supported()document the exemption, and the latter degrades to a connectivity-only check when the protocol issovereign. -
Two new MCP tools,
a8_list_egressesanda8_unlock_user, wrapping the SDK methods above. See below for the six more this release adds and for the resulting tool count. -
ENABLE_REQUEST_LOGGINGnow does something. The key shipped in every bundled config file and was documented as inert — no SDK code read it. Setting it totruenow logs oneINFOline 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 everyDEBUGline in the SDK to get it. Credentials are removed before anything is written: fields whose names containtoken,auth,password,secret,credentialorkeyare masked, as is the token carried by thesetauthcommand, 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 remainsfalse. 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"isTrue, 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_CACHEandA8_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 fromcredentials.yamlalone and never opens the shipped config files, so the same three variables — plusA8_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 incredentials.yamlto pin it for that client instead. Two keys were deliberately left as literals:DEBUG_MODEandENABLE_ENCRYPTIONare 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"isTrue, so a switch turned off in the environment would have read as on.1,true,yesandonmean 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_typesaccepts a bare string naming one type onextract_logs,extract_all_logsandexport_logs_to_file, alongside the list. Both are shapes the wire itself accepts:extractlog'stypetakes 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 againstVALID_LOG_TYPESand still goes through the space-name wire translation.validate_log_types()now agrees with whatextract_logsaccepts — a bare"AUTH"returnsTruewhere it previously returnedFalse.- A comma-joined string is refused rather than split.
"AUTH,SESSION"raisesValidationErrornaming 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")returnsFalsefor the same reason. -
One further contract change on the same method:
validate_log_types([])now returnsFalsewhere it previously returnedTrue. The old implementation ended inset(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 thatget_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 addspartner_SSO_sign_cert, which this one does not return. Identify the org withorg_nameororg_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 throughcreate_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_policyjoins 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_attrsand 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_configwas 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-standaloneresearch sessions only. The browsing and MCP docstrings, which used to say only that its locations are not published, now explain how to find them: calllist_egresseswithsession_type="toolbox-standalone"and look for"protocol": "sovereign"in a location'scategories. Or passWorldwithprotocol: "sovereign"and let the platform choose. -
The
list_egressesdocs explain why an org can list no egress while its users have some. Selecting byorg_idororg_namereports 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. Thelist_egressesanda8_list_egressesdocstrings and the browsing reference now say so, and point tousernameoruser_idfor what a user can select. -
a8_create_browsing_urlacceptsegress_info, asa8_create_contextdoes. Combining it withegress_regionorcategoriesis rejected. -
default_egress_for_task_type()insilo_sdk.utilsreturns the egress a harvest task gets when none is given:New York Cityfor asset and wget tasks,Worldfor 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 MCPa8_clear_proxy_policyalso 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.jsonorsample_config.json— and raisedNo configuration file foundwithout one, even with everyA8_*variable set. That leftpip install silo-sdk-mcpwith 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.versionin the MCP handshake carried the version of the underlyingmcplibrary (for example1.30.0) instead of the installedsilo-sdk-mcprelease, so a client log or diagnostic could not tell which release it was talking to. It now reports the SDK version. AddUserResult.bypass_codeis typedstr | None.add_user()returnsNonethere when the platform issues no bypass code; the type saidstr.-
MCP
a8_extract_logswithfallback_per_type=trueno 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 noAUTHrows in the window lost the fact thatAUTHworked and onlyENCfailed. It now raises only when no type succeeded, and otherwise returns the page withtype_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 answers400and says, in as many words, to passorg_idinstead, and all that reached the caller wasFailed 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, andstatus_code,response_dataandrequest_idare carried through to the raisedBrowsingAPIErrorso you can branch on them directly. Related: an organization name shared across the hierarchy must be disambiguated withorg_id— this was not previously documented anywhere. SiloErrorgained aserver_messageproperty, which returns the platform's own explanation from the error body, orNonewhen the response carried nothing usable.messagestays 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 ofresultwas already raised.{"result": {"error": ...}}was not: the SDK saw aresultkey, 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
errorkey. Calls that previously returned{"error": "..."}now raiseSiloErrorwith that message, carrying the full response element asresponse_data. Code that tested for the key will no longer see it; code that already relied on exceptions gets the failure it was expecting. Aresultdict whoseerroris empty or falsey is untouched and still returned. find_files()documented a set of returned fields that the platform does not send. The docstring listedsize,created_ts,modified_tsandmetadata; the reply actually carriesbucket_id,file_id,name,path,type,content_type,file_size,create_user_id,create_username,create_ts,expire_ts,uploading_untilandsession_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 thea8_find_filesMCP tool, along with the note that results are passed through unfiltered, so a field the platform adds shows up without an SDK change.session_idis 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_idandcreate_username. And it listedsession_idunconditionally; 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
StreamHandlerto thesilo_sdklogger whenever that logger had none of its own, without checking whether the root logger — whichsilo_sdkrecords propagate to — already had one. A host that had calledlogging.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 sixAPI 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, yoursilo_sdklines now render in your format rather than both. ConfigBuilder.with_default_policy()wrote a key nothing reads. It setdefault_policyin lower case, while the shipped config files,a8_validate_configand the bundled examples all look forDEFAULT_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 writesDEFAULT_POLICY, and the sample configuration file written bycreate_sample_config()has been corrected the same way. Action required if you read the key back yourself: code doingconfig["default_policy"]on a builder result will now raiseKeyError; readconfig["DEFAULT_POLICY"].find_files(limit=...)andlist_files(limit=...)now return at mostlimitfiles. 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 smalllimitand relied on getting everything back was relying on the bug and will now getlimitentries.-
bulk_download_asyncno 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 amax_concurrentabove 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, andmax_concurrentabove 100 raisesValidationErrorrather 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. ItsReturns:section namedcreated_ts,started_ts,completed_tsandtask_metadata; the method passes the platform's record straight through, so the real names arecreate_ts,start_ts,end_tsandtask_results, and reading any of the four documented names raisedKeyError. Onlywait_for_completion_async()adds those aliases, layered on top of the raw record —wait_for_completion()does not, despite polling the same call. All threeReturns: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 —hostnameis the worker that claimed the task, not the target being harvested, andattempt_countincludes the attempt currently in flight. - There is no
runningtask status. It was documented as one of five for a long time and the platform has only ever sent four:wait,claimed,doneanderror. A task that is actively executing readsclaimed, 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 theTaskRecordtype, in the harvest how-to guide, in the SDK docstrings and in the MCP tool descriptions fora8_find_harvest_task,a8_list_harvest_tasksanda8_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
TaskRecordtype 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 — sotask["hostname"]andtask["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 aKeyError, 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 astror abool, 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_idthe 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, sodelete_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 raisesOrgManagementAPIErrorinstead 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 forisinstance(result, list)and so returned[]on every call. It now returnsstr, matchingadd_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 andlist-shaped assertions are the only things affected. Callget_proxy_policy()to read back the resulting list.add_proxy_policy()anddelete_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 exactlyorg_idandorg_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 atget_org()for reading back a change.get_user()andlist_users()documented about two thirds of what they return.get_user()omittedis_locked,failed_login_attempts,oob_lockedandoob_lock_expires_at, so there was no documented way to tell a locked account from a suspended one;list_users()omittedcreate_ts,last_authorized_tsandcustom_fields. Both lists are now complete, andlist_users()states that its record is not the same shape asget_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 — anerrorin place of the result, and anerrornested inside aresult— therefore arrived back at the caller looking like task details. The envelope has nostatus, so it was written into the status cache as a real task, andwait_for_completion()reportedUnexpected task status: Nonesome 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_tasksappended 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
errorkey. A lookup that previously returned{"error": "..."}now raisesHarvesterAPIErrorcarrying 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'stypeas a list; this SDK joined the requested types into a comma-separated string, which the server parses as one unknown type and rejects withValueError: invalid log type. Only single-type calls survived that, because a one-element join has no comma in it — soextract_logs(log_types=["AUTH", "SESSION"]), the shape the docstrings have always shown, has been failing since the method existed, andextract_all_logsinherited 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" sentURL, "Security Events (EXPLOIT + CLIPBOARD)" sentEXPLOIT, "Download + Upload" sentDOWNLOAD, and "Extract All Log Types" sentAUTHrather 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 thattypetakes 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
URLwhile its recorded response complained aboutNOSUCHTYPE; 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_logsand 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. Withfallback_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 highestnext_seqit had seen. IfAUTHreached 5000 whileSESSIONonly reached 2000, the caller was told to resume at 5000 and everySESSIONrow 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 reportingis_more, so a resumed page will repeat rows for every type whose ownnext_seqwas higher — so deduplicate byseq_idwhen paging a fallback response. That is the deliberate trade: duplicates are visible and recoverable, gaps are neither. When no type reports more,next_seqis the lowestnext_seqany type reported, so a poller keeps advancing; types listed intype_errorsmust be re-requested from the originalstart_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
ENCwith 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_proxywas missing from bothVALID_VISUAL_PARAMSandVALID_VIDEO_PARAMS, so a visual or video task setting it failed locally before any request.wgetis likewise a task type the platform accepts, and was rejected. Both are now accepted.wgetsharesasset's parameter family and wire shape, differing only inrequest_type(see Changed for howwgetis validated). - One definition, three gates.
VALID_TASK_TYPESexisted as a hardcoded literal in three places — the class attribute, the task builder andvalidate_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 insilo_sdk.utils.harvester_utils, which the other two reference, and a test asserting every gate accepts every canonical type. -
renderis 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_sessionhad no way to setpolicyorexpires, so a research session launched through MCP ran under the org's default policy with no expiry and no way to change either — whilea8_create_context, wrapping the same underlying operation, exposed both.a8_create_contextin turn could not setauto_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_sessionflattensbrowser_profileandcategoriesinto scalar arguments that suit flat-argument callers, anda8_batch_requesttakes atoken_typerather than anauth_tokenso 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 "afile_id-scopedfindfileslookup, 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 ignoresfile_idthere, 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 promisedfile_id,name,path,size,content_typeandupload_ts; the endpoint returnsfile_idalone, and the method passes the response body through unchanged. Reading any of the other five raisedKeyErrorfor 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 atget_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
sizeandid, which the API does not send. Search results reportfile_sizeandfile_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— reportedcreated_ts,started_tsandcompleted_tsasNoneon every call. The SDK read those three names off the server record, but the wire sendscreate_ts,start_tsandend_ts, so all three lookups missed and returned nothing. No error, no warning, andHarvestTaskInfodeclares 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_tsisnulluntil the task finishes, which is the server's own answer rather than a miss. - There is no
progressfield and there never was. The docstring offered one "if available", and the platform reports task state throughstatusandfinishedonly — it sends no percentage. Anything readingprogressgetsNoneevery time. Every place that claimed otherwise now says so: thefind_harvest_tasksummary 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 intoTaskProgress.update_status()positionally, where the second parameter ismessage, notprogress— 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_tsandcompleted_tswere declared as requiredstr. They are Unix epoch floats, and the latter two areNoneuntil the task is claimed and finishes respectively. Nowfloat | 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 raisedUserManagementAPIError: Unexpected result format: user addedfor 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 withbypass_codeset toNone.- 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_codecan now beNoneon success. The key is always present in the returned dictionary. Test the value, not the key —if "bypass_code" in resultno longer tells you a code was issued, andresult["bypass_code"]may beNoneon 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()listedcreated_ts,user_count,settingsandparent_org. The record carriescreate_ts,current_usersandprovisioning_info, and the parent comes back as two fields,parent_org_idandparent_org_name. Nosettingssub-dict exists — thea8_get_orgtool went further and documentedsettings.proxy_policy,settings.allow_list,settings.deny_listandsettings.session_type, none of which appear in any response. Useget_proxy_policy()/a8_get_proxy_policyfor an org's proxies.get_org_children()listedcreated_ts,user_countanddepth. The listing carriescurrent_users,provisioning_infoandvanity_url, and reports no creation timestamp and no hierarchy depth at all. (Thea8_list_child_orgstool does return adepthfield, but it computes that itself whenrecursive=True; it does not come from the platform.)create_org()promisedvanity_urlandcreated_ts. The create response containsorg_idandorg_nameand nothing else. Callget_org()with the neworg_idfor the full record.extract_logs()listedtotal_count,organdlog_typesalongside the three real fields. The response islogs,is_moreandnext_seqonly. There is no total — the endpoint pages, andis_moreis the only answer to whether more rows exist.-
get_context()listedcreated_ts,expires_tsandpolicy; the real names arecreate_tsandexpires, and the configuration comes back undercontext_data. Nine further fields the context record does carry — includingenabled,last_useandcommonality— were undocumented and are now listed. Thea8_get_contexttool repeated the same three wrong names. -
wait_for_completion_async()documented aworker_idfield 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 ishostname. 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_paramsis real. A reader checking whether the merge was necessary would have gone looking forprogressin a response and found nothing. It now names fields the server actually sends:task_params,attempt_count,hostname,finished,target,task_results. -
a8_health_checkwas under-reporting what an admin token unlocks. Itscapabilitiesmap 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 maskedapi_key,apikeyandprivate_key. Anything else —ipsec_key, for one — was rendered in full in the "unexpected response format" warning and in theSiloErrormessage 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_taskandbulk_create_and_monitor_asyncgave every taskNew York, NY, which is not one of the six datacenter locations asset and wget tasks accept. With no egress given, they now useNew York Cityfor asset and wget tasks andWorldfor other types. A location you set, or a bulk-levelegress_info, still applies. The sync and async harvest demos sendNew York Cityto their asset tasks, and theegress_infodocs on the harvester methods note the asset and wget location limit. -
The async harvester reports server errors.
wait_for_completion_asyncread an error in place of the result as "no result yet" and polled until timeout, and failed on an error nested inside the result withFailed to monitor async task: 0. Both now raiseHarvesterAPIErrorwith the server's message on the first poll, aswait_for_completiondoes.create_harvest_task_asyncreported a rejected task asUnexpected response formatwith the raw response; it now raises with the server's error message. -
create_context()andget_context()keep the server's error message. An error nested inside the result was reported only asFailed to retrieve context IDorNo context data found. TheBrowsingAPIErrornow carries the server's message, for example for a deleted context. -
create_sample_config()writesDEFAULT_EGRESS_INFOinstead of the unusedDEFAULT_EGRESS_TAG, matchingconfig/default.json. -
get_session_report(org_name=...)takes a path below the token's own org, and the docs now say so. The server resolvesorg_namerelative to the org the token belongs to, so passing that org's own name — which the docs implied, and whichscripts/session_report.pydid by default fromA8_TOP_ORG— has always been refused withPermissionDenied. Omit every identifier to report on the token's own org; giveorg_nameonly for a child org, as"Sales"or"Sales/EMEA". The docstring, thea8_get_session_reportMCP tool description, the Postman request and the script are corrected accordingly. scripts/session_report.pyno longer readsA8_TOP_ORG. With no--orgit now reports on the token's own org;--orgtakes a child org path.-
hierarchy=Truedoes not change the result. Child orgs are included by default, with or withoutorg_name, which live API testing confirms. The flag is kept for compatibility and documented as such. -
The bundled scripts in
scripts/now honorA8_CONFIG_ENV. Each one loadedconfig/default.jsonby explicit path, which skips the selected profile's own config file (config/<profile>.json). A profile that maps its tokens there, rather than throughA8_*variables, was silently ignored, and the script ran with whatever tokens.envheld. They now callload_config(), which applies the profile.export_logs.pyandscheduled_visual_harvest.pyalso readA8_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 honorA8_CONFIG_ENVtoo, and no longer print part of a token. The demos loadedconfig/default.jsonby explicit path, with the same effect as the scripts above. They now callload_config(), andconfig_demo.pyshows that instead of loadingconfig/<profile>.jsonon its own, which never merged it with the base config and failed for a profile with no file of its own.config_demo.pyalso 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.envrather thanconfig/default.json, which is version-controlled and must hold only${A8_*}references. -
The configuration docs no longer claim an unset
${VAR}raisesConfigurationError. It never did. Substitution replaces an unset variable with an empty string, andload_config()succeeds. A missing token is reported only when a client that needs it is constructed, asMissing 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, thenconfig/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 asfalse; any other key, such asAPI_URL, keeps the empty string, and no built-in default replaces it. The docstring andconfig/README.mdnow say so. The examples README, the examples page and theexamples/config_demo.pytext no longer say variables are substituted intoconfig/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 inconfig/README.mdto a nonexistentexamples/config/directory is replaced with links that exist. No SDK behavior changed. -
The MCP server's
credentials.yamlsubstitution falls back to the default for an empty variable.${VAR:-default}resolved to""whenVARwas set but empty, because only an unset variable fell back. It now behaves likeload_config()and bash: an empty variable uses the default too. This affects the HTTP transport, which readscredentials.yaml; the stdio transport already usedload_config(). -
scripts/key_manager.pyno longer prints any part of a stored key or token.list-keysshowed the first and last characters of each key, andshow-tokenshowed the first eight and last four characters of the token — or the whole token when it was 16 characters or shorter.list-keysnow shows only whether each key is set, andshow-tokenreports that a token is stored and where.pvtkey.txtandtoken.txtare also now written readable by their owner only (mode 600), including when the file already existed with wider permissions. -
Asset harvest examples in the
HarvesterAPIandTaskBuilderdocstrings 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_ENVis no longer used to build a.envfile 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 assub/leakcould load a file outside the intended name pattern before the error. The name is now checked first, andload_config()called without a path raises the sameConfigurationError. AnA8_CONFIG_ENVset inside.env.<profile>no longer switches the profile either. It used to change whichconfig/<profile>.jsonwas merged after.env.<profile>had been chosen by the original name, so the two came from different profiles. -
The docs and
.env.exampledescribe whereA8_CONFIG_ENVcan be set. They said it must come from the shell, that it could not be set in.env, and that it defaulted toproduction. There is no default profile. A value in.envselects the profile, and one exported in the shell takes precedence over it. The configuration guide,README.mdandconfig/README.mdnow also note that for every other variable, a value in.envreplaces one exported in the shell.examples/config_demo.pynow reports the profile after loading the config, so a profile set in.envis shown rather than(none). -
The script docs no longer say
org_usage_report.py,user_usage_report.pyandaudit_org_users.pyreadA8_TOP_ORG. All three take a required--organd ignore the variable. The published scripts page now matches the scripts README: it documentscreate_context.py, drops a maintainer-only script that is no longer inscripts/, saysA8_BUCKET_IDbelongs in.envrather thanconfig/default.json. The scripts README'sscheduled_visual_harvest.pyexample now uses"Dallas, TX", which the script accepts, instead ofDallas, 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_ORGnow reachesscripts/move_users.py. The script and its docs used it as the default destination org, butconfig/default.jsonnever mapped it, so it was always empty.config/default.jsonnow maps it toTARGET_ORG.
Changed¶
wgetharvest tasks now getasset's rules everywhere, because that is what they run as. The platform acceptswgetand then runs it as anassettask, converting it before any parameter check or egress lookup, so every check that applies toassetnow applies towgettoo:- Egress. TOR egress is rejected for
wgetas it is forasset, and a location outside the six asset egress locations now produces the same warning. The per-location connectivity/protocol cross-check is skipped forwget, as forasset, since the asset pool is selected differently. all_filesis rejected forwgetas it is forasset.- Parameters and builder options.
get_valid_params("wget")returns the asset parameter set instead of raising,validate_task_params()no longer rejectswgetas an unknown type, andTaskBuilder("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 withwget_params),ASSET_TASK_TYPES(asset,wget), and, for task status,ACTIVE_TASK_STATUSESandIN_PROGRESS_TASK_STATUSES, all insilo_sdk.utils.harvester_utils. -
VALID_TASK_TYPESis afrozenset. It was a mutablesetshared by every gate that checks task types, so mutating it changed what all of them accept.HarvesterAPI.get_valid_task_types()still returns a freshset. -
UploadResultnow describes onlyfile_id, because that is allupload_file()returns. The type also listedname,path,size,content_typeandupload_ts, none of which are in the upload response, so code written against the type would readNoneor raiseKeyError. Pass thefile_idtoget_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-pagingExtract Next Page) were moved across, and the separateSetuprequests 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.createin the collection parented the new org off theorg_namealready in the environment, so the parent/child chain — create an org, then create a child of that org using theorg_namethe server returned — appeared nowhere, despite three separate requests creating an org. The org lifecycle flow gainsFLOW — Create Sub-Org, which readsorg_id/org_nameout of the previous response rather than from configuration, andFLOW — 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 MetadataandDelete Filedemandedbucket_idand usedfile_id; the whole user-management folder demandedorg_namefor calls that address a user by name alone; two org flow steps demandedorg_idfor calls keyed onorg_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,availabilityorprotocolwas checked against a table of per-location capabilities compiled into the SDK, and a combination the table did not record raisedValidationErrorbefore 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 bothcreate_harvest_task()andcreate_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-dictegress_infoorcategories, 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 alogging.WARNINGon thesilo_sdk.harvesting.egress_validationlogger 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 catchingValidationErroraround 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_categoriesand the harvest tool'segress_infodocumentation point ata8_list_egressesas 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_typesasks the platform instead of reporting the SDK's built-in list. The tool exists so a model can discover what to pass toa8_extract_logs, and a compiled-in list quietly answers a slightly different question than the one asked. It now callsget_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_infoandsovereignexamples 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 anegresses_urlvariable — the existingapi_urlcarries 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
errorelement besideresult, anerrorstring nested insideresult, a bare0from an update that matched nothing, an empty list from a search that found nothing, and — for the/ctxshorthand, which is not a command-array call — an actual400with an HTML body. Among them is a harvest task that was accepted with atask_idand only failed at execution, itslast_errornaming 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_filesandlist_filesreturn directory entries alongside files, distinguishable by acontent_typeofFolder, and a directory cannot be downloaded — feeding one todownload_fileorbulk_download_asyncgets 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 oncontent_typebefore 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'suse_chunkedargument 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, whileuse_chunked=Truestreams 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_asyncandbulk_create_and_monitor_asyncwere taggedASYNC_VARIANTwith async_ofnaming a method they merely call rather than one they are the async form of —bulk_download_asyncis not an asyncdownload_file, it is a concurrent orchestration over many of them. A newASYNC_CONVENIENCEmethod type describes async-only orchestration with no sync counterpart, and these three now carry it along with awrapslist 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_REGISTRYgains 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_usernameandsovereign_location, each with a fallback when left empty (World,World,usernameandWorld). The sovereign request sendsWorldwith thesovereignprotocol, so the platform chooses among the org's sovereign locations, and Create Asset Collection Task usesNew 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 abrowse_context_id. The exception is Create Research Context — Sovereign Egress withsovereign_usernameempty: 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 byorgnameand its current 400, 401 and 403 error bodies, and a log extract made up ofSESSIONrecords. 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 whenadmin_token,usernameorurlis 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_logsreturned it as a page with no logs, soextract_all_logsstopped paging and reported success, andget_log_sequence_inforeported no logs. Both now raiseLogExtractionAPIErrorwith the server's message.extract_logs_per_typerecords the error intype_errorsfor that type and still returns the others.find_filesandlist_filesreturned[], the same as an empty bucket, for an error or for any result that is not a list. They now raiseFileAPIError; an empty bucket still returns[].-
resolve_orgreturned every error message, including invalid-token andNo org matchingerrors, as a single entry incandidates, and resolved a nested error to the name passed in with an emptyorg_id. It now raisesOrgManagementAPIError, as its docstring said. For an ambiguous name,candidatesholds the matching org paths taken from the server's message rather than the message itself. -
An unknown
egress_regionnow warns instead of raising.BrowsingAPI.create_context()logs a warning for anegress_regionmissing from the SDK's location list and still sends the request, as it does foregress_info. A non-stringegress_regionstill raisesValidationError. -
create_context.pyandbulk_create_contexts.pydefault toWorldfor research contexts. With--researchand no--egressthey fell back toDEFAULT_EGRESS_INFO(New York) with datacenter categories, which an org without that egress rejects. They now sendWorldwith no categories.--egressbehaves as before. -
scripts/scheduled_visual_harvest.pyaccepts every egress name a visual task takes.--egresswas checked against cities only, soWorld, regions and countries were refused.--list-egressnow listsWorld, 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_idandtask_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_idandtask_idvalues 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_asyncpreviously 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. FileAPIno longer rebuilds its TLS trust store on every download. The CA bundle is parsed once when the client is constructed, matching whatHarvesterAPIalready 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
FileAPIErrorlike every other filesystem failure in these methods, rather than a bareOSErrora caller would have to catch separately. - A
Retry-Afterheader 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 raisedValueErrorout of the response handler — a crash instead of theRateLimitErrorthe 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_asyncwrote 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-Afteron 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_URLvalues with embedded credentials are rejected. A URL of the formhttps://user:password@hostwas 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_ROOThas governeda8_upload_fileanda8_download_filesince 0.14.0, buta8_download_harvest_resultanda8_export_logs_csvwere 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 anauthorized_keyswith attacker-influenced content is code execution, anda8_export_logs_csvalso 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 insideMCP_FILE_ROOTand 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_ROOTto 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_resultadditionally 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, notaiohttp. Thecreate_ssl_contextdocstring — which is published in the API reference — showed anaiohttpconnector example that does not apply to this SDK and would not work as written. It now shows thehttpxusage the SDK actually supports.aiohttpis not and has never been a dependency. .env.exampledocuments the MCP server's bind and allowlist settings.MCP_BIND_HOSTandMCP_ALLOWED_HOSTSwere 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. Thedocker-compose.mcp.ymlcomment 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-mcpdistribution on PyPI —pip install silo-sdk-mcpnow works. It contains no code. It is an alias that depends onsilo-sdk[mcp-server]at an exact matching version, so it installs precisely whatpip install "silo-sdk[mcp-server]"installs and nothing else. The MCP server continues to ship insidesilo-sdkas thesilo_sdk_mcppackage and thesilo-sdk-mcpconsole 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 forsilo-sdk-mcponly 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 bysilo-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 defaultpip installresolved 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 thedecryptandlegacy-decryptextras — 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.1in themcp-serverextra (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-serverextra could not install at its own declared minimums, and its lowest supported version crashed the HTTP transport.mcp[cli]>=1.0.0admitted releases with nomcp.server.transport_securitymodule — added in 1.10.0 — which the server imports unconditionally to configure DNS-rebinding protection. Any such release installed cleanly and then raisedModuleNotFoundErrorthe moment the server was started over HTTP or SSE. Separately, the extra declaredfastapi>=0.111.0alongsidemcp, and their transitive Starlette requirements were disjoint (<0.38against>=0.39), so installing the declared minimums failed outright with a resolution error. Both are corrected;uvicorn[standard]moves to>=0.31.1because that is what the newmcpfloor requires. pyyaml>=6.0.0→>=6.0.2in themcp-serverextra. 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¶
fastapiis no longer a dependency of themcp-serverextra. It was never imported. The MCP server is built onFastMCP, 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 importedfastapiand 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_TIMEOUTconfig key (A8_LOG_EXTRACT_TIMEOUT) — a dedicated request timeout forLogExtractionAPI, separate from the SDK-wideREQUEST_TIMEOUT. It ships unset, andLogExtractionAPIfalls 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_ROOTenvironment variable for the MCP server — the directory (orPATH-style list of directories) thata8_upload_fileanda8_download_fileare allowed to read and write. Defaults to a dedicatedsilo_sdk_mcp_filesdirectory 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, andRETRY_DELAYare now environment-templated inconfig/default.json, soA8_REQUEST_TIMEOUT/A8_MAX_RETRIES/A8_RETRY_DELAYtake 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. Unlikebulk_create_contexts.py, the destination URL is optional: omitting--urlopens the session's default start page, which is the usual way to start an ad-hoc Silo for Research session. One of--useror--orgis 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-pythonis 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.1tag remains the last release that installs on 3.10. Installing this version or later on 3.10 fails cleanly at resolution time with aRequires-Python: >=3.11error rather than installing something broken, so pin tov0.13.1or 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. LogExtractionAPInow 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 withPermissionDenied: log.extract already in progressuntil 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-secondREQUEST_TIMEOUTstill governs the sub-second admin and browsing calls that dominate the SDK. SetA8_LOG_EXTRACT_TIMEOUTto override.- The new default raises the extraction timeout but never lowers it. Anyone who had already set
REQUEST_TIMEOUTabove 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 explicitLOG_EXTRACT_TIMEOUTstill wins outright, including one belowREQUEST_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", not30— so making the timeout and retry keys templatable would otherwise have handed a string torequestsand brokenvalidate_harvester_config()'sisinstance(value, (int, float))check with a misleading "must be a positive number".REQUEST_TIMEOUT,LOG_EXTRACT_TIMEOUT,MAX_RETRIES,RETRY_DELAY, andSTATUS_CACHE_TTLare coerced after substitution and before defaults are applied, on both config-loading paths. A non-numeric value now raisesConfigurationErrornaming the key instead of failing later somewhere unrelated.DEFAULT_MAX_USESis 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, andSTATUS_CACHE_TTLare seconds, andrequestsis happy with2.5;MAX_RETRIESis 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 whileA8_RETRY_DELAY=2.5did 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_TIMEOUTfails every request before it is sent, so it is now aConfigurationError; 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 as1. - 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 thesilo-sdkdistribution the server ships in. The package path was the last name that did not match, andsilo-mcpwas ambiguous enough to be worth retiring outright. - Action required: update the server key and
commandin 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 userthenclaude mcp add silo-sdk-mcp --scope user -- <command>. - Action required (importers and
python -musers):python -m silo_mcpbecomespython -m silo_sdk_mcp, and anyfrom silo_mcp… import …becomesfrom 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). Thesilo-sdk-mcpconsole script and, for editable installs, the generated import finder both bake the module path in at install time and do not update on agit pull— until you reinstall, the console script fails withModuleNotFoundError: No module named 'silo_mcp'. Note thatpython -m silo_sdk_mcprun from the repository root keeps working regardless, because the current directory is onsys.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 orphanedsilo_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_mcptosilo_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]inpyproject.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
Srules are flake8-bandit — the same rule set bandit ran — andDruns under thepep257convention flake8-docstrings defaulted to, with the same rules disabled as before.E/W/F/B/C4cover 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 andpip-auditfor dependency CVEs. Pylint is simply gone — it ran with--exit-zero, so it never gated anything. - One formatting pass touched 26 files.
ruff formatis 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/andsetup_venv.pywere 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 nowdict[str, Any],Optional[X]isX | None, and thetypingimports they needed are gone. Ruff'sUPrules 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 shipspy.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]"andpre-commit install --install-hooks.black,isort,flake8,banditandpylintare no longer dev dependencies, and.flake8has been deleted. OrgManagementAPI.delete_org()now raises instead of returningFalse. The method advertisedTrueon success andFalseon failure, butFalsewas unreachable: the server answers a delete with either a confirmation payload or an error, and an error already raisedOrgManagementAPIError. TheFalsebranch could only be reached by a response shape the API does not produce, so in practice the method already either returnedTrueor raised — while its signature invited callers to writeif 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 anOrgManagementAPIErrornaming 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 OrgManagementAPIErrorinstead of testing the result. Code that only checks truthiness keeps working unchanged, because the success return is stillTrue. Code that treatedFalseas "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_orgMCP tool description carried the same two errors and has been corrected to match. devnow carries a.dev0version suffix while it is ahead of the last tag. Until nowdevreported the same__version__as the release it branched from, so apip install -efrom adevcheckout was indistinguishable from the tagged release despite differing behavior — which made "which SDK produced this result?" unanswerable during a support investigation.devwill be set to<next>.dev0immediately 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_filetook any local path and sent its contents to the storage API;a8_download_filetook 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 intoa8_upload_file("/proc/self/environ")exfiltrates everyA8_*token the server process holds, and a download aimed at~/.ssh/authorized_keysor 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_filesdirectory under the system temporary directory, created on demand. It is deliberately not the working directory and not the whole temp directory. SetMCP_FILE_ROOTto point somewhere real; it accepts aPATH-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_ROOTto 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_HOSTSpreviously 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.0and an unauthenticated local attacker, and warnings scroll past. The server now exits with a non-zero status and an explanation. An explicitly emptyMCP_ALLOWED_HOSTSis treated the same way, rather than as "allow everything". --credentialspointing 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_responsematched 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 containingtoken,password,secret,api_key,credential,private_key,session_idorauthorization, 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_URLmust use HTTPS. Nothing checked the scheme, so anhttp://value — from a typo, a copied internal note, or an attacker-writable config file — silently sent every API token in cleartext. A non-HTTPSAPI_URLis now aConfigurationErrorat 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_SSLconfig key. It appeared inconfig/default.json,config/production.jsonand the configuration reference, but no SDK code read it — certificate verification is unconditional on both the synchronous and theaiohttppaths, against thecertifitrust store. A documented switch that does nothing is worse than no switch: it invites someone to set it tofalse, 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.shwrites 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.envat mode0600, via an atomic replace so an interrupted run cannot truncate a file full of credentials. Existingexport A8_*lines are recognized and replaced rather than duplicated. Tokens already sitting in a~/.zprofilefrom an earlier run should be removed by hand and rotated.scripts/run_postman_eval.shno longer passes tokens on the command line. Every account on the host can read the full argv of a running process out ofps, and CI runners log the command they invoked. The five tokens now travel in a short-lived0600environment 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.examplecarried 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. .dockerignoreexcludes the per-environment config files.config/qa.json,config/eng.jsonandconfig/demo.jsonare gitignored, so unlikedefault.jsonandproduction.jsonnobody 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) andS323(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. seccureis now upper-bounded (>=0.5.0,<1.0) in the optionallegacy-decryptextra, matching every other dependency. It has had one release since 2014, so a surprise1.0would 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.mcpcopies the whole working tree, and.dockerignorecarried no entry forsilo_sdk_mcp/credentials.yaml— so on any machine where the server had been run locally,docker buildcopied live API tokens into an image layer..gitignoredoes 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 toMANIFEST.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_TIMEOUTbut never lowers it — was keyed onLOG_EXTRACT_TIMEOUTbeing absent from the configuration. Butconfig/default.jsonshipped"${A8_LOG_EXTRACT_TIMEOUT:-600}", which resolves to600whether or not the environment variable is set, so the key was always present and always looked deliberate. Anyone who had raisedREQUEST_TIMEOUTabove 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 explicit600is 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 withLOG_EXTRACT_TIMEOUT must be a number, got ''. Because every CLI script underscripts/loads the configuration at import time, that turned--helpinto a traceback on a machine with noA8_*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()andprint_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# nosecmarker, which has been inert since bandit was replaced by Ruff'sSrules — Ruff readsnoqa.)scripts/run_postman_eval.shignoredA8_CONFIG_ENVand always ran against production. The variable was documented in the script's own usage text, but the Production environment file was hardcoded — soA8_CONFIG_ENV=eng ./scripts/run_postman_eval.shran 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 nowengrather thanprod: 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.
E501was listed in Ruff'signore, andignoretakes precedence overselect— so themax-line-length = 100setting alongside it, and the changelog note in this release saying the lint gate still fails at 100, described a check that could not fire.E501has 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.exampleorsilo_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 onMANIFEST.into reach the wheel. Dockerfile.mcpinstalled 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 onlypyproject.tomlproduced an import finder with an empty mapping, and the later source copy could not retroactively fix it. Inside the image thesilo-sdk-mcpconsole script failed withModuleNotFoundErrorand imports only worked from/app. This was masked by the container's ownCMD, which usespython -mand therefore picks the package up from the working directory regardless. The source is now copied before the install.- Numeric values in
credentials.yamlwere 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 acredentials.yamlwritten in the documented"${A8_REQUEST_TIMEOUT:-30}"style handedrequeststhe string"30"and every call from an HTTP-transport client failed with aTypeErrorfrom inside the HTTP layer. Both loading paths now share one coercion step, so they cannot drift apart again. silo-sdk-mcp --credentialsdefaulted to a path relative to the current directory. The default wassilo_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/appin the image).- The Compose file's
MCP_ALLOWED_HOSTSdefault ignoredMCP_BIND_HOST. Binding the container to a non-loopback address left the DNS-rebinding allow-list pinned to127.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 fromMCP_BIND_HOST, and an explicitMCP_ALLOWED_HOSTSstill overrides it. - The remote-deployment documentation described the superseded SSE transport as the default. The setup and overview pages showed
--transport sse, the/sseendpoint in every reverse-proxy example, and anMCP_CREDENTIALS_FILEenvironment variable the server does not read; the published port example also bound0.0.0.0. They now documentstreamable-httpand its/mcpendpoint, bind the published port to loopback so a reverse proxy is the only route in, and note whereMCP_ALLOWED_HOSTSmust list the public hostname.ssestill works and is still documented as the fallback for older clients. - The same correction reached the packaged
silo_sdk_mcp/README.mdand the CLI's own--helptext, which still described--portand--credentialsas SSE-only and showed a/sseclient 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--hostdefaults to0.0.0.0— every interface — and points at--host 127.0.0.1behind a TLS-terminating proxy. - The configuration reference omitted seven shipped config keys.
TOP_ORGappeared only as a script-scoped environment variable despite being required bya8_validate_configand probed bya8_health_check, andENABLE_STATUS_CACHE,STATUS_CACHE_TTL,RATE_LIMIT,DEFAULT_EGRESS_INFO,DEFAULT_POLICYandENABLE_REQUEST_LOGGINGwere absent entirely — all six ship inconfig/default.json, so readers met them for the first time in a file the docs never explained. TheA8_REQUEST_TIMEOUT/A8_MAX_RETRIES/A8_RETRY_DELAYmappings were missing from the environment-variable table as well. All are now documented, along with a note thatORG_VANITY_URLis not the API org name —TOP_ORGis. Two are documented as inert rather than as working settings: nothing readsENABLE_REQUEST_LOGGING, andRATE_LIMITis shape-validated but never enforced, so the SDK does not throttle on your behalf. - The remote-deployment documentation showed a two-client
credentials.yamlthat 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__andconfig.__version__. Both were sub-package version numbers with no consumers, and both had silently drifted from the distribution version (the MCP sub-package, then namedsilo_mcp, sat at0.10.3through four releases;configat0.8.2since April).silo_sdk.__version__is the single source of truth — asDEFAULT_USER_AGENTalready 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 defensiveraisestatements 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_retriestoa8_extract_logsskips 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 bya8_parse_saml_metadataand the SSO-import CLI command): fetch_metadata_url()now only acceptshttp/httpsURLs 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 clearValueErrorbefore any fetch is attempted.- MCP downloads that omit
output_pathnow 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 withdefusedxmlinstead of the standard library parser, which rejects entity-expansion ("billion laughs") payloads and external entity references (XXE) up front instead of resolving them.defusedxmlis now a required dependency.parse_saml_metadata()no longer silently uses the firstEntityDescriptorwhen 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 optionalentity_idparameter 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-GCMInvalidTag, the exact signal that a ciphertext was tampered with or corrupted — and returned a dict with just anerrorfield 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 anerrorkey, anddecrypt_logs()appended it straight into the "successfully decrypted" list. Decryption/authentication failures are no longer swallowed: decrypt_log_entry()now raises the newLogDecryptionErroron 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 newtrack_failed=Trueto instead collect failed entries into a separate list and keep processing the rest of the batch — mirroring the existingtrack_missingparameter 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
errorkey should instead catchLogDecryptionError(or passtrack_failed=Trueand 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 insidefinalize(), which runs after plaintext chunks have already been written viaupdate()— 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 thepvtkey.txtstore (necessary since a multi-line PEM value can't be represented on the store's singlename=valueline), butload_private_keys()never decoded it back — so the documentedgenerate_key_pair()→add_key_to_store()→load_private_keys()→ decrypt workflow hard-failed with aValueErrorinsideload_pem_private_key().load_private_keys()now automatically detects and decodes base64-encoded PEM values written byadd_key_to_store(); Legacy passphrases,.pemfile paths, and hand-written raw PEM values are left untouched. - ENC log schema listed the wrong field name. The
ENCCSV schema inlog_schemas.pylistedenc_algorithm, but the Authentic8 API documentation's Extract Log response example confirms the actual field returned alongside encrypted log entries isencryption_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 toLegacyregardless of its actual encryption type. Corrected toencryption_type. - HTTP retries could re-execute non-idempotent requests. The shared
Retryadapter allowedPOSTon 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_methodsis now restricted to idempotent verbs only (GET,HEAD,PUT,DELETE,OPTIONS). batch_requestreturned the injectedsetauthacknowledgment 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_usersalso now applies the same "user not found" soft-success translationdelete_user()already had, so the batch and single delete paths present a consistent result contract.modify_fileposted directly to the base URL, missing theapi/path segment, instead of routing through the shared request helper like every other command.upload_file/download_filebypassed the shared HTTP session entirely (via barerequests.post), skipping session-level retry/proxy/User-Agent configuration.get_file_infoperformed a full-bucketfindfilesscan 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 emptyA8_*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 fallbackAPI_URLalso embedded a redundant/api/(producing a double/api/and 404s), andConfigBuilderbypassed.envfile loading entirely, unlikeload_config(). A shell/process-levelA8_CONFIG_ENVnow also reliably takes precedence over a conflicting value merely defined in.env. - Bulk async harvest raised
KeyErroron a per-taskurlkey and ignored each task's ownegress_infoin 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. Bothurlandurlsper-task keys are now accepted, and per-taskegress_infois 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-parsingValidationErrorwas 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_checkreported stale tool-capability counts (drifted from the actual registered tool list) and always reported0latency 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 destructivea8_delete_org/a8_delete_partner_sso_configtools now reject a blank/whitespace-onlyorg_namebefore 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 markedpartial: Trueinstead — a partial row is never filtered out byinclude_inactive=False, so a fetch failure can no longer masquerade as a genuinely idle user.OrgManagementAPI.get_session_report()also now strictly validates the documentedMM-DD-YYYYdate format (previously a loose length/dash-count check silently accepted ISOYYYY-MM-DDdates 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 cyclicget_org_childrenresponse could produce duplicate rows. All org-tree traversals (list_users_recursive,get_org_usage_report,get_user_usage_report,get_org_tree, and themove_users.py/find_user_orgs.pyscripts) now share a single, consistently cycle-guarded and deduplicated traversal implementation. a8_list_users_recursivewas missing its own parameter-validation error handling, so an invalidmax_depthsurfaced 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_usersnow 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; theorg/org_namefield 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. Theorg_namefield on returned rows is now the full path for any sub-org.OrgManagementAPI.get_org_tree()/a8_get_org_tree()— fetched each node'sorg_id/user count by bare name; now uses the full path internally (the nested tree's ownorg_namefield 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_nameis 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 atDEBUGlevel, giving no signal that the returned data was incomplete. These failures are now logged atWARNING, 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)droppedorg_id— the flattening step only copiedorg_name/current_users/depthfrom each tree node, silently omitting theorg_idfieldget_org_tree()provides. Now included.
Added¶
org_idon everyget_org_tree()node —a8_get_org_tree()/OrgManagementAPI.get_org_tree()now include a stableorg_idper node, in addition toorg_nameandcurrent_users.org_idis 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 thecategoriesparameter's structure and values; previously invalidcategorieswere silently accepted and forwarded to the API.
Changed¶
- Retired the Lebanon egress location — no longer accepted as a valid
egress_region/egress_info.namevalue. - Removed the
EGRESS_LOCATIONSmodule-level constant fromsilo_sdkandsilo_sdk.browsing. UseBrowsingAPI.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_blockwithenable/disablevalues (previously documented asadblockwithblock/allow, which the API rejects). - Corrected the domain blocklist policy type name to
domain_block(previouslydomain_deny) across SDK docstrings, MCP tool help, and the browsing reference docs. - The default
User-Agentheader 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 reportedsilo-sdk/0.10.0).
Changed¶
- Clarified the
browser_chrome: seamlessconstraint: 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_profilefieldstimezone(IANA name) andlanguages(Accept-Language string), in addition toosandbrowser.
[0.10.2] - 2026-05-07¶
Added¶
- Setup script (
setup_venv.py --dev) now verifiesmcpandsilo_mcpimports 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.yamllists 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.tomldependency pins corrected formcpandfastapiextras.
[0.10.1] - 2026-05-05¶
Changed¶
- Package rename:
mcp_server→silo_mcp— the MCP server package is nowsilo_mcp/. The CLI entry point issilo-mcp(wasauthentic8-mcp). Install withpip install "silo-sdk[mcp-server]". - Packaging fixes: wheel now correctly includes
silo_mcp/and all sub-packages.
Fixed¶
- Replaced
aiohttpwithhttpxfor async HTTP to resolve a dependency conflict. - Windows compatibility fix for
cleanup.pyand test path handling.
[0.10.0] - 2026-05-05¶
Added¶
- Egress location details —
get_egress_locations(include_details=True)returns enriched per-city metadata includingconnectivity,availability, andprotocolinstead of plain name strings. Backward-compatible: default remainsinclude_details=False. EGRESS_LOCATION_DETAILS— new static dict insilo_sdk/browsing/isolation_api.pymapping 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 acceptsinclude_details: bool = True(enriched output by default for LLM callers). Existing callers usinginclude_details=Falseget the prior flat-string behavior. - TOR protocol per location —
protocolfield 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_TYPESinegress_validation.pychanged from{"private", "shared"}to{"private", "public"}per the Harvester API documentation (April 2026, p.4)."shared"was never a valid backend value; any caller passingavailability="shared"would have silently received no egress results from the backend.EGRESS_LOCATION_DETAILS,CategoriesTypedDict, 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. protocolfield not exposed —get_egress_locations(include_details=True)previously extractedconnectivityandavailabilityfromEGRESS_LOCATION_DETAILSbut silently droppedprotocol. All three fields are now returned.
Changed¶
a8_list_egress_locationsMCP tool default changed from returning flat strings to returning enriched dicts (include_details=True). Callers that need flat strings must now passinclude_details=Falseexplicitly.
[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; enhanceda8_health_checkwith 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_typeina8_extract_logs, idempotency hints ina8_add_user/a8_create_org, optionalbucket_idina8_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.pyvalidatesLOG_TYPE_FIELDSagainst 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.pydemonstrates the full ENC log extract-then-decrypt workflow with per-type breakdown and optional JSON output - Private key template —
examples/pvtkey.txt.exampledocuments thepvtkey.txtformat 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 CLItests/test_log_stats.py(66 tests) — all 11 analysis functions, formatters, and file loadingtests/test_mcp_logging_tools.py(27 tests) — MCP retry-on-lock behavior and exception handlingtests/test_export_logs_csv.py(28 tests) — CSV enhancement flags and resume state- Log parsing utilities — New
silo_sdk/logging/log_utils.pymodule 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.pyextracts multiple log types sequentially with configurable pauses and automatic retry on backend lock contention - Log analytics script —
scripts/log_stats.pywith 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_logsgainsretry_on_lock,retry_delay, andmax_retriesparameters for automatic lock contention handling - CSV export enhancements —
scripts/export_logs.pygains--expand-json,--expand-nested, and--parse-egressflags for richer CSV output with dot-notation column expansion - NEXUS log type — Added
NEXUStoVALID_LOG_TYPESandLOG_TYPE_FIELDSfor Nexus AI conversation events (fields:conversation_id,message_type,org_name,toolbox_name, etc.) - ENC wrapper schema — Added
ENCtoLOG_TYPE_FIELDSwith 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(defaultFalse).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(defaultTrue),active_only(defaultFalse). 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 filteringscripts/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 hierarchyget_user_usage_report()— Collect per-user session statistics across an org hierarchy
Changed¶
- Log type field schemas synced with
logtype_headers.iniv1.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_TYPEScount — 25 → 26 (added NEXUS)LOG_TYPE_FIELDScount — 24 → 26 (added NEXUS and ENC)get_session_report()extended — Added optionalorg_id,user_id, andhierarchyparameters.org_id/org_nameare mutually exclusive;user_id/usernameare mutually exclusive.hierarchyparam enables subtree reporting (undocumented API feature).- MCP
or Nonenormalization — All optional string parameters insilo_mcp/tools/orgs.pynow useparam or Noneto prevent empty-string validation errors when AI assistants pass""for omitted optional params. a8_download_fileanda8_download_harvest_resultMCP tools —output_pathparameter is now optional. When omitted:a8_download_filesaves to temp directory using the original filename from Silo storage metadata (falls back to file ID if metadata unavailable)a8_download_harvest_resultsaves to temp directory asharvest_<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(defaultTrue). Returns a flat list withorg,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": [...]}.candidatesis 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_filecontentparameter — Accepts an optionalcontent: stras an alternative tofile_path. Provide exactly one offile_pathorcontent; providing neither or both raisesValueError.run-mcp.shnow appends stderr to/tmp/mcp-server.logfor post-disconnect diagnosis.
[0.8.7] - 2026-04-01¶
Fixed¶
org.update— API returns flat dict; SDK expected list → now checks dict firstdelete_partner_sso_config— API returns{"deleted":1,"status":1}dict; SDK expected int → fixed type checkget_session_report— API error responses embedded inresultdict were silently returned as success → now raisesOrgManagementAPIErrordelete_harvest_task— result extracted from wrong response index → fixed to use_extract_api_resultupload_file— omittedpathparam 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 onPOST /getfile/; confirmed via live test that/getfile/accepts multipart/form-data only (id+authfields); all three corrected - Postman harvest task wire format —
Create Asset Collection TaskandFLOW — Create Visual Harvest Taskhadtask_type/urlsat command level and params as dicts; corrected torequest_typeinsidetask_paramswith{name, value}array format docs/maintenance/api-recommendations.md— correctedsession_reportwire command fromorg.session_reporttosession_report; documented thatinclude_childrenis silently ignored and:hierarchyis 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 asa8_update_contextMCP toolextract_logs()include_suborgsparameter — optionalbool; whenTrueincludes log records from child organizations; omitted from request when not providedfind_harvest_task()finishedparameter — optionalbool; whenTruefilters to completed tasks only, whenFalsefilters to in-progress tasks only; omitted from request when not provided. Also exposed ona8_find_harvest_taskMCP tool
Changed¶
- MCP
a8_upload_file,a8_find_files,a8_list_files— docstrings clarify thatbucket_idis 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 fromsilo_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()andto_csv()shared by scripts.silo_sdk/utils/org.py—walk_org_tree()(BFS generator) andprint_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 usersscripts/batch_user_provisioning.py— bulk user creation from CSV with dry-runscripts/analyze_log_storage.py— log type availability and sequence infoscripts/compare_org_configs.py— proxy policy / user count drift across org hierarchyexamples/batch_operations_demo.py— bulk context creation with per-item error capture, retry, and cleanup summary.- MCP tests:
tests/test_mcp_credentials.pyandtests/test_mcp_tools.py(skipped automatically whenmcppackage is not installed). tests/test_utils_formatting.pyandtests/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.pyandscripts/session_report.py— table output now uses sharedformat_table()fromsilo_sdk.utils.formatting.- CI matrix — dropped Python 3.9 (EOL October 2025); minimum is now Python 3.10.
Updated
requires-python = ">=3.10". blackupgraded>=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 viasys.version_info; no longer breaks on 3.10+ either).tests/test_import_error— changedmock.patch(string)tomock.patch.object(module)for reliable behavior across Python 3.10–3.13.tests/test_mcp_tools.py— addedpytest.importorskip("mcp")guard so CI does not fail when themcppackage (in[mcp-server]extra) is not installed.- Postman collection flow assertions — corrected Log Pipeline and Context Lifecycle flows:
get_log_info(non-existent command) →extractlogprobe;resultarray →result.logsarray;AUTH,SESSIONmulti-type → singleAUTHfor this token. docs/getting-started/authentication.mdanddocs/concepts/tokens.md— removedget_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 viaextractlogprobe (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. Acceptsbrowse_context_idplus any combination ofcontext_data,max_uses,expires,name, andenabled. Only supplied fields are updated; omitted fields are unchanged. Registered incommand_registry.py.extract_logs()include_suborgsparameter — optionalboolthat, whenTrue, includes log records from child organizations in the extraction result. Omitted from the request when not provided (no change to existing behavior).singleharvest task type — added toVALID_TASK_TYPES. Single-URL non-recursive fetch; useswget_params; available from all egress locations (unlikeasset).VALID_ASSET_EGRESS_LOCATIONS— new constant inegress_validation.pylisting the six datacenter locations valid forassettasks: Singapore, Dubai, Frankfurt, Sao Paulo, Johannesburg, New York City / New York, NY.- Three missing egress locations added to
VALID_EGRESS_LOCATIONSfor 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, andtest_user_management_api.py. Total: 1,124 tests, 99.28% coverage. - Postman collection v0.8.5 —
session_reportrequest corrected, newUpdate Contextrequest added to Browsing Isolation section,include_suborgsshown in Extract Logs example.
Changed¶
get_user()signature —usernameandemailare 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")orapi.get_user(email="u@x.com").get_session_report()signature —include_childrenparameter removed. Confirmed via live API testing this was never a real API parameter and was silently ignored by the server. The method now acceptsorg_name,start_date,end_date, andusername.- Asset task egress validation —
create_harvest_task(task_type="asset", ...)now raisesValidationErrorif the suppliedegress_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_LOCATIONSreorganized — list sorted consistently within regions; three previously missing locations added.
Fixed¶
scripts/session_report.py— removed--no-childrenCLI flag andinclude_childrenkwarg that was silently ignored by the API.scripts/move_users.pyandexamples/user_demo.py—get_user()calls updated from positional argument to keyword argument (username=) to match the new signature.silo_mcp/tools/orgs.pya8_get_session_report— removedinclude_childrenfrom the MCP tool signature.
Breaking changes¶
get_user(username)positional call → useget_user(username=username)orget_user(email=email). Passing both raisesValidationError.get_session_report(include_children=...)→ remove the argument; it no longer exists.create_harvest_task(task_type="asset", egress_info={"name": "Tokyo"})→ raisesValidationError. Asset tasks must use one of the six valid datacenter locations.
[0.8.4] - 2026-03-16¶
Added¶
update_partner_sso_config— newOrgManagementAPImethod 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— newOrgManagementAPImethod to permanently delete a Partner SSO configuration, its partner user, and the org itself. Irreversible.- Both new methods registered in
command_registry.pyand 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 animport-metadatasubcommand 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 bymanage_sso.pyand thea8_parse_saml_metadataMCP tool.a8_parse_saml_metadataMCP 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_settingsmissing,list_harvest_tasksmissing,get_log_infomissing) and resolved gaps (proxy policy write ops confirmed aspolicy_proxies.set/add/delete).- 20 new unit tests for SSO methods (1055 total).
Changed¶
create_partner_sso_config/get_partner_sso_configdocstrings — 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_configdocstring 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, andvanity_urlas optional here vs required for SSO.get_log_sequence_info()reimplemented — theget_log_infocommand is not recognized by the ext API. Now implemented as aCONVENIENCEmethod that probes viaextractlog(start_seq=0, limit=1, type=AUTH). Returnsmin_seq,is_more,next_seq;max_seqandtotal_logsare explicitlyNone(not available via ext API).extract_logs()bug fixed — was failing to unwrap the{"result": {...}}response envelope, causinglogsto always be empty andis_more/next_seqto beNone. The fix adds a single unwrap step consistent with how all other API modules handle responses.export_logs.pyfixed —show_info()updated to displayearliest seq/is_more/next_seqinstead of the unavailablemin_seq/max_seq/range. Defaultstart_seqlogic now usesor 0to gracefully fall back when no logs are found at the probe point.a8_create_orgMCP tool description updated to match correctedcreate_org()docstring.a8_extract_logsMCP tool — corrected Returns (removed fabricatedtotal_count; documents actuallogs/is_more/next_seqfields).a8_get_log_sequence_infoMCP tool — updated to reflect probe-based implementation;max_seq/total_logsdocumented asNone.create_harvest_taskdocstring — corrected wire key names (wget_params/vid_paramsnotasset_params/video_params); full wire format example now shows correcttask_paramsnesting.download_filedocstring — added Note documentingPOST /getfile/endpoint with form-dataid+auth(not a command-array request).create_contextdocstring — added Note about GET/ctx/shorthand withresponse=parameter; updatedcreate_ctx_urlto cross-reference.create_partner_sso_configdocstring —parent_org_nameclarified as required in practice.docs/concepts/wire-protocol.md— new Non-Command-Array Endpoints section documentingPOST /getfile/,POST /putfile/, andGET /ctx/withresponse=parameter table.- MCP
a8_create_harvest_task— warns against invalidtask_typevalues (screenshot,pdf,mhtml);a8_create_partner_sso_configclarifiesparent_org_namerequirement. - Postman collection updated: 60 standalone requests now have real sanitized API response
examples; harvest task wire format corrected;
Download Filecorrected toPOST /getfile/;Upload Fileform field names corrected (name/path);GET /ctx Shorthandupdated withresponse=urlparameter. scripts/README.md—update_collection_examples.pydocumented with usage examples, SSO org reset procedure, and required env vars.- Version bumped to
0.8.4acrosspyproject.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 fromOrgManagementAPI— theorg.update_settingscommand is not recognized by the ext API. Org settings (session limits, MFA, download policies) are not configurable via the API.a8_update_org_settingsMCP tool removed.list_harvest_tasks()removed fromHarvesterAPI— thelist_harvest_taskscommand is not recognized by the ext API. Usefind_harvest_task(task_id)for point lookup, or extractHARVESTlog type entries to find task IDs.a8_list_harvest_tasksMCP tool removed.settingsparam removed fromcreate_org()— was unverified and unused.
Added (proxy policy management — confirmed real API commands)¶
get_proxy_policy()— newOrgManagementAPImethod usingpolicy_proxies.getset_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 withproxies_deletedandproxies_not_foundarrays- 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);portandtypeoptional (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: seamlessonly available for non-catchall users; catchall users are always forced to minimal (Ribbon Mode) egress_regionvalidation added toBrowsingAPI.create_context()— validates againstVALID_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 forsilo_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 Reportrequests;List Tasks/Update Org Settingsremoved (commands do not exist) ctx_urlenv var added to all four Postman environment files — enables multi-environment GET /ctx testing without hardcoded production URLsproxy_nameenv 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 nestedresult.error— captures errors that HTTP 200 responses previously hid - Eng environment support in
update_collection_examples.py:A8_CONFIG_ENV=enguses.env.engoverrides; env-specific state files (.collection_update_state.eng.json); Newman env URLs derived fromA8_API_URL; 57/60 standalone requests updated against eng dest_pathchanged 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_urloptional here but required for SSO; org hierarchy root documented; SCIM context addedbrowser_chromepolicy type added toBrowsingAPIclass docstring (3 values:standard,seamless,minimal); Seamless UI auth constraint documentedadd_proxy_policydocstring — clarifies multiple proxies can be added in a single calldelete_proxy_policydocstring — 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.pyandisolation_api.py:Asia-Pacific,Africa & Middle East,Central & South America docs/maintenance/api-recommendations.mdexpanded with: proxy policy resolution,list_harvest_tasksconfirmed 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_contextfixed:"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(notsso_config_id, which doesn't exist) - Auto-generated
test_org_nameandtest_sso_org_namein pre-request scripts - Proxy policy and
org.update_settingstests made graceful for permission-limited accounts GET /ctxshorthand URL corrected (removed erroneous/api/prefix)Find Files — Date Rangerequest added demonstratingfile_type,:created_before,:created_afterfilter 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_usesplacementHarvesterAPI.create_harvest_task: validtask_typevalues,task_params→vis_paramsmappingLogExtractionAPI.extract_logs:log_typeslist→comma-joined string, date→epoch transformsOrgManagementAPI.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 toBrowsingAPI,HarvesterAPI, andLogExtractionAPIclass docstrings so mkdocstrings rendersVALID_TASK_TYPES,VALID_VISUAL_PARAMS,VALID_LOG_TYPESas structured tables in the MkDocs API reference- MkDocs nav: new "Postman & Newman" section linking to the Newman testing guide
Fixed¶
.mcp.jsonpointed to outdated repository path; corrected.- MCP server
mcp-serverextras not installed;pip install -e ".[mcp-server]"now required for the MCP server to start (installsmcp,fastapi,uvicorn) - Wire format example in developer docs showed incorrect
"data": {…}nesting; corrected to flat params - Wire format example in
docs/concepts/wire-protocol.mdshowed wronglistusersstructure docs/getting-started/authentication.md:API_URLexample had erroneous/api/suffixdocs/getting-started/quickstart.md: misleadingtask_type="screenshot"→task_type="visual"docs/concepts/async.md:task_type="screenshot"→task_type="visual"docs/getting-started/quickstart.mdand 13 other files: stalev0.8.1/v0.8.2version references updated tov0.8.3- User-Agent string defaults updated from
silo-sdk/0.8.1→silo-sdk/0.8.3inapi_client.py,config.py,config_builder.py,config/default.json,config/production.json silo_mcp/__init__.pyversion bumped to0.8.3
Changed¶
- Postman environment defaults updated:
org_namemaps toA8_TOP_ORG(notA8_ORG_VANITY_URL) - Postman collection
info.versionset to0.8.3 - Developer tooling documentation expanded: flat-param rule,
create_contextexception,orgvsorg_nameparam distinction,A8_TOP_ORGvsA8_ORG_VANITY_URLdistinction
[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_apistosilo_sdk - Exception base class renamed from
A8APIErrortoSiloError A8APIErrorkept 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.ymlmoved to.gitlab/ci.ymlfor 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/toDocumentation/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.ymlreusable 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 decryptionstandard_decrypt_chunked()— 32 MB streaming for large filesdecrypt_video_file()— atomic write with temp fileload_private_keys(),decrypt_log_entry(),decrypt_logs()- Private key file format:
name=valuepairs inpvtkey.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_afterparameter 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 supportkey_manager.py— CLI for managing private keys and API tokensbulk_create_contexts.py— bulk browsing context creation from URL listsession_report.py— organization session report generatorfile_manager.py— file storage CLI (list, search, download, info)scheduled_visual_harvest.py— daily visual captures withrun_afterschedulingdecrypt_files.py— batch log file decryptionmove_users.py— user migration between organizations- SDK demos in
examples/: user_demo.py,org_demo.py,log_demo.py,decrypt_demo.pybrowsing_demo.py,file_demo.py,config_demo.pyharvest_demo_sync.py,harvest_demo_async.py- CONTRIBUTING.md with development workflow
.env.exampletemplate with allA8_*environment variables- Unified Postman API Reference Collection (100% SDK coverage)
Changed¶
examples/renamed tosdk_examples/for clarity (reverted toexamples/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
randomwithsecretsfor 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_tagdecorator 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-requestsadded 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
A8APIErrorwith 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 withbase/,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